Customize web server

Default Nginx configuration

The default Nginx static service has following configuration:

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name _;
    root {{.DocumentRoot}};

    location / {
        try_files $uri $uri/ /index.html;
    }

    access_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=info default_short;
    error_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=error;
}

The configuration contains 2 variables:

• {{.DocumentRoot}} is replaced by the run.documentRoot attribute from the zerops.yaml. If the attribute is not specified, the default value /var/www is used.

Customize Nginx configuration

Follow these steps to customize the Nginx configuration in Nginx static service:

1. Create a .tmpl file with the Nginx configuration in your repository.

2. Optionally use following variables:

• {{.DocumentRoot}} is replaced by the run.documentRoot attribute from the zerops.yaml. If the attribute is not specified, the default value /var/www is used.

Example:

root {{.DocumentRoot}};

• {{.Environment.ENV_NAME}} is replaced by the env variable value. The env variable must be either defined in run.envVariables in zerops.yaml or set as a secret or generated env variable in Zerops GUI.

Caution

Use the .tmpl file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.

3. Check that your Nginx configuration is consistent with Zerops requirements:

• Do not use IP addresses in the listen directive
• If you use other ports than :80 in the listen directive, add them to the run.ports in your zerops.yaml as well.
• Do not use the port :443. All the incoming https:// traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your Nginx static service as a http:// on the port :80.

4. Add the siteConfigPath to the run section of your zerops.yaml

zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: nodejs@latest

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - vendor
        - public

    # ==== how to run your application ====
    run:
      documentRoot: public

      # OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
      siteConfigPath: site_config.tmpl

5. Ensure that the build.deployFiles contains the folder with the siteConfigPath or add the path to the Nginx config file to the deployFiles list. Zerops will deploy the file to the runtime container(s).

6. Trigger the build & deploy pipeline.

SEO & Prerender Support

Single Page Applications and JavaScript-heavy sites render content client-side, which most crawlers can't process—they see an empty page instead of your content. This affects traditional search engines, social media platforms, and AI tools like ChatGPT, Perplexity, and Claude.

Built-in Prerender.io Integration

The default Nginx configuration includes automatic Prerender.io support. When enabled, it detects crawler requests (including AI crawlers) and serves them pre-rendered HTML while your users get the full interactive experience.

Setup

To enable prerender support:

1. Set the PRERENDER_TOKEN environment variable with your Prerender.io token (see environment variables)
2. Optionally set PRERENDER_HOST if using a custom prerender server

The Nginx configuration will automatically handle the rest—no additional configuration needed.