Platform.sh User Documentation

Serve static sites

Upsun Beta

Access our newest offering - Upsun!

Get your free trial by clicking the link below.

Get your Upsun free trial

Static site generators are a popular way to create fast sites. Because there’s no need to wait for responses from servers, the sites may load faster.

As an example, this documentation is built using a tool called Hugo and served by Platform.sh as a static site. You can see the entire repository on GitHub, including its app configuration.

To learn how to serve your static site using Platform.sh, you can start with the required minimal app configuration and build on it, or jump straight to an example of a complete configuration.

Minimal app configuration Anchor to this heading

To successfully serve a static site using Platform.sh, you need to set up a minimal app configuration similar to the following:

.platform.app.yaml
app:
  # The type of the application to build.
  type: "nodejs:20"

  # The web key configures the web server running in front of your app.
  web:
    locations:
      /:
        # Static site generators usually output built static files to a specific directory.
        # Define this directory (must be an actual directory inside the root directory of your app)
        # as the root for your static site.
        root: "public"
        # Files to consider when serving a request for a directory.
        index:
          - index.html

See more information on the required minimal settings:

Add more features Anchor to this heading

Allow static files but not dynamic files on PHP containers Anchor to this heading

If you have a PHP container, you might want to enable client-side scripts but disable server-side scripts.

To enable static files that don’t match any rule while disabling server-side scripts on a PHP container, use the following configuration:

.platform.app.yaml
web:
    locations:
        '/':
            ...
            scripts: false
            allow: true

See more information on locations properties.

Create cache rules Anchor to this heading

You can create sensible cache rules to improve performance. For example, if you publish new content regularly without updating images or site files much, you might want to cache text files for a day but all image files for longer.

To do so, use a configuration similar to the following:

.platform.app.yaml
web:
    locations:
        '/':
            ...
            expires: 24h
            rules:
                \.(css|js|gif|jpe?g|png|svg)$:
                    expires: 4w

Conserve the server Anchor to this heading

Because your site is completely static, it doesn’t need the server to be running. To set a background process that blocks the server and conserves resources, use the following configuration:

.platform.app.yaml
web:
    commands:
        start: sleep infinity

You can also use this place to start small programs, such as a script to handle 404 errors.

Complete example configuration Anchor to this heading

.platform.app.yaml
name: app

type: 'python:3.11'

web:
    locations:
        '/':
            # The public directory of the application relative to its root
            root: 'public'
            # The files to look for when serving a directory
            index:
              - 'index.html'
            # Disable server-side scripts
            scripts: false
            allow: true
            # Set caching policy
            expires: 24h
            rules:
                \.(css|js|gif|jpe?g|png|svg)$:
                    expires: 4w

    commands:
        # Run a no-op process that uses no CPU resources since this is a static site
        start: sleep infinity

Is this page helpful?