zeropsio · tikinang · Sep 8, 2026 · Sep 7, 2026
diff --git a/apps/docs/content/guides/zerops-yaml-advanced.mdx b/apps/docs/content/guides/zerops-yaml-advanced.mdx
@@ -92,12 +92,12 @@ run:
         values: { X-Frame-Options: "'DENY'" }
 ```
 
-- **`cors`**: Sets Access-Control-Allow-Origin. `"*"` auto-converted to `'*'`
-- **`redirects[]`**: `from` (wildcards `*`), `to`, `status`, `preservePath`, `preserveQuery`
-- **`headers[]`**: `for` (path pattern), `values` (header key-value pairs)
-- **`root`**: Custom root directory
+- **`cors`**: Sets Access-Control-Allow-Origin, -Allow-Methods, -Allow-Headers and -Expose-Headers to the same value. `"*"` auto-converted to `'*'`
+- **`redirects[]`**: `from` (exact path, or prefix with trailing `*`, or absolute URL matched on the domain), `to`, `status` (omit for a masked redirect, `301`/`302` only for absolute `from`), `preservePath`, `preserveQuery` (both only with a `status`)
+- **`headers[]`**: `for` (same matching as `from`, `"/*"` for everything, `"/"` is the homepage only), `values` (header key-value pairs, quotes included: `"'DENY'"`). Only the best-matching rule applies, rules are not merged.
+- **`root`**: Folder served, relative to `/var/www`. The Static service ignores `run.documentRoot`, this is its replacement.
 
-**DO NOT** use on non-static services -- silently ignored.
+**DO NOT** use on non-static services -- silently ignored. Conversely `documentRoot` is ignored on Static, and `siteConfigPath` is ignored on Static whenever `routing` is present.
 
 ---
 
@@ -135,7 +135,7 @@ Available runtimes and versions are listed in **Service Stacks (live)** -- injec
 - The OS is part of the base value — `ubuntu/nodejs@22` or `alpine/nodejs@22` — with no separate `os:` field; use the same prefix in `build.base` and `run.base` (a bare `nodejs@22` resolves to Alpine, and `run.base` rewrites the service OS on deploy)
 - PHP: build `<os>/php@X`, run `<os>/php-nginx@X` or `<os>/php-apache@X` (different bases)
 - Deno: ships only as `ubuntu/deno@X` (no Alpine image). Gleam runs on both Alpine and Ubuntu.
-- Static sites: build `alpine/nodejs@latest`, run `static`
+- Static sites: build `alpine/nodejs@latest`, run `alpine/static` (the bare `static` shorthand means the same)
 - `@latest` = newest stable version
 
 ---
diff --git a/apps/docs/content/nginx/faq.mdx b/apps/docs/content/nginx/faq.mdx
@@ -6,7 +6,13 @@ description: Get quick answers to your related questions about Nginx from freque
 import { FAQ, FAQItem } from '/src/components/Faq';
 
 <FAQ>
+  <FAQItem question="What is the difference between the Nginx service and the Static service?">
+    Both serve static files with Nginx. The [Static service](/static/overview) generates the Nginx configuration from a declarative `run.routing` section (redirects, headers, CORS) and has Prerender.io built in. The Nginx service gives you the default configuration or your own file via `run.siteConfigPath`, which is the way to go for `proxy_pass`, caching or extra ports. See the [comparison](/static/overview#static-or-nginx-service).
+  </FAQItem>
+  <FAQItem question="Why is my run.routing section ignored?">
+    `run.routing` is only read by the Static service. The Nginx service ignores it without an error. Either switch `run.base` to `alpine/static`, or express the redirects and headers in a custom configuration set via [`siteConfigPath`](/nginx/how-to/customize-web-server).
+  </FAQItem>
   <FAQItem question="How do I enable SEO optimization with prerender.io?">
-    Zerops provides built-in prerender.io support. Simply set the `PRERENDER_TOKEN` environment variable with your prerender.io service token. See our [prerender.io documentation](/nginx/how-to/env-variables#prerenderio-support) for details.
+    Prerender.io support is built into the [Static service](/static/overview#seo-with-prerender), not into the Nginx service. On the Nginx service you can add the prerender rules to your own configuration set via [`siteConfigPath`](/nginx/how-to/customize-web-server), or switch to the Static service.
   </FAQItem>
 </FAQ>
diff --git a/apps/docs/content/nginx/how-to/build-pipeline.mdx b/apps/docs/content/nginx/how-to/build-pipeline.mdx
@@ -8,6 +8,10 @@ import UnorderedCodeList from 'docs/src/components/UnorderedCodeList';
 
 Zerops provides a customizable build and runtime environment for your static content.
 
+:::note Nginx service vs Static service
+This page covers the Nginx service (`run.base: alpine/nginx@latest` or `ubuntu/nginx@latest`). The [Static service](/static/overview) (`run.base: alpine/static`) uses the same build and deploy pipeline but is configured through `run.routing` instead of `documentRoot` and `siteConfigPath`. The `run.routing` section is ignored by the Nginx service. See [Static or Nginx?](/static/overview#static-or-nginx-service).
+:::
+
 :::tip Two Deployment Approaches
 You can use the Nginx service in two ways:
 - **Runtime only**: Deploy pre-built static files directly (no build phase needed)
@@ -35,9 +39,6 @@ zerops:
       # REQUIRED (if using build). Set the base technology for the build environment:
       base: nodejs@latest
 
-      # OPTIONAL. Set the operating system for the build environment.
-      # os: ubuntu
-
       # OPTIONAL. Customize the build environment by installing additional packages
       # or tools to the base build environment.
       # prepareCommands:
@@ -62,8 +63,8 @@ zerops:
 
     # ==== how to run your application ====
     run:
-      # OPTIONAL. Sets the base technology for the runtime environment:
-      base: nginx@latest
+      # OPTIONAL. Sets the base technology and OS for the runtime environment:
+      base: alpine/nginx@latest
 
       # OPTIONAL. Customize the runtime Nginx environment by installing additional
       # dependencies to the base Nginx runtime environment.
@@ -139,14 +140,14 @@ zerops:
 
     # ==== how to run your application ====
     run:
-      # OPTIONAL. Sets the base technology for the runtime environment:
-        base: nginx@latest
+      # OPTIONAL. Sets the base technology and OS for the runtime environment:
+      base: alpine/nginx@latest
       ...
 ```
 
 <p>
   The base runtime environment contains {data.alpine.default}, the
-  selected major version of Nginx, <a href="/references/cli">Zerops command line tool</a> and `composer`, `git` and `wget`.
+  selected major version of Nginx, <a href="/references/cli">Zerops command line tool</a>, `git`, `wget` and `curl`.
 </p>
 
 :::info
@@ -169,7 +170,7 @@ zerops:
     run:
       # OPTIONAL. Sets the base technology for the runtime environment:
       base:
-        - nginx@latest
+        - alpine/nginx@latest
       prepareCommands:
         - zsc add go@latest
       ...
@@ -181,14 +182,7 @@ To customize your build environment use the `prepareCommands` attribute.
 
 ### os
 
-_OPTIONAL._ Sets the operating system for the runtime environment.
-
-Following options are available:
-
-- `alpine`
-- `ubuntu`
-
-Default value is `alpine`.
+_DEPRECATED._ The operating system is part of the `base` value: `alpine/nginx@latest` or `ubuntu/nginx@latest`. Do not set `os` separately.
 
 We are currently using following os version:
 
@@ -250,7 +244,7 @@ _OPTIONAL._ Customizes the Nginx runtime environment by installing additional de
 
 <p>
   The base Nginx environment contains {data.alpine.default}, the selected
-  major version of Nginx, <a href="/references/cli">Zerops command line tool</a> and `composer`, `git` and `wget`. To install
+  major version of Nginx, <a href="/references/cli">Zerops command line tool</a>, `git`, `wget` and `curl`. To install
   additional packages or tools add one or more prepare commands:
 </p>
 
@@ -314,7 +308,7 @@ You can configure your prepare commands to be run in a single shell instance or
 
 <p>
   The prepare runtime container contains {data.alpine.default}, the
-  selected major version of Nginx, <a href="/references/cli">Zerops command line tool</a> and `composer`, `git` and `wget`.
+  selected major version of Nginx, <a href="/references/cli">Zerops command line tool</a>, `git`, `wget` and `curl`.
 </p>
 
 The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the build section of your chosen technology.
@@ -412,12 +406,30 @@ zerops:
 _OPTIONAL._ Sets the custom Nginx configuration.
 
 :::info
-If you don't set your custom configuratiin Zerops applies the [default](/nginx/how-to/customize-web-server#default-nginx-configuration) configuration.
+If you don't set your custom configuration Zerops applies the [default](/nginx/how-to/customize-web-server#default-nginx-configuration) configuration.
 :::
 
-The file must be deployed in the runtime container. Enter the path to the file relative to the `/var/www` folder.
+The file must be deployed in the runtime container. Enter the path to the file relative to the `/var/www` folder. A file with the `.tmpl` extension is rendered as a template (`{{.DocumentRoot}}`, `{{.Environment.NAME}}`), any other file is used verbatim.
 Read more about the [web server customization](/nginx/how-to/customize-web-server).
 
+```yaml
+zerops:
+  # hostname of your service
+  - setup: app
+    # ==== how to build your application ====
+    build:
+      ...
+      deployFiles:
+        - dist
+        - site_config.tmpl
+
+    # ==== how to run your application ====
+    run:
+      documentRoot: dist
+      # OPTIONAL. Path to your Nginx configuration, relative to /var/www.
+      siteConfigPath: site_config.tmpl
+```
+
 ### envVariables
 
 _OPTIONAL._ Defines the environment variables for the runtime environment.

diff --git a/apps/docs/content/nginx/how-to/create.mdx b/apps/docs/content/nginx/how-to/create.mdx
@@ -11,6 +11,10 @@ import ResourceTable from '/src/components/ResourceTable';
 
 The Nginx static service contains the Nginx web server optimized for your static content. Nginx static service is highly scalable and customisable to suit both development and production.
 
+:::tip
+If you only need redirects, headers and CORS on top of your static files, the [Static service](/static/overview) configures them declaratively without any Nginx configuration. See [Static or Nginx?](/static/overview#static-or-nginx-service).
+:::
+
 ## Create Nginx static service using Zerops GUI
 
 First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Nginx static service:
@@ -84,19 +88,19 @@ project:
 services:
   - # service name
     hostname: app
-    # service type and version number in nginx@{version} format
-    type: nginx@latest
+    # service type, OS and version number in {os}/nginx@{version} format
+    type: ubuntu/nginx@latest
     # defines the minimum number of containers for horizontal autoscaling
     minContainers: 1
-    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
+    # defines the maximum number of containers for horizontal autoscaling.
     maxContainers: 6
     # optional: create env variables
     envSecrets:
       S3_ACCESS_KEY_ID: 'P8cX1vVVb'
       S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
 ```
 
-The yaml file describes your future project infrastructure. The project will contain one Nginx version 8.1 service with default [auto scaling](/nginx/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nginx/how-to/build-pipeline#ports). Following secret env variables will be configured:
+The yaml file describes your future project infrastructure. The project will contain one Nginx version 1.22 service with default [auto scaling](/nginx/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nginx/how-to/build-pipeline#ports). Following secret env variables will be configured:
 
 ```env
 S3_ACCESS_KEY_ID="P8cX1vVVb"
@@ -122,8 +126,8 @@ project:
 services:
   - # service name
     hostname: app
-    # service type and version number in nginx@{version} format
-    type: nginx@latest
+    # service type, OS and version number in {os}/nginx@{version} format
+    type: ubuntu/nginx@latest
     # optional: vertical auto scaling customization
     verticalAutoscaling:
       cpuMode: DEDICATED
@@ -136,9 +140,9 @@ services:
       startCpuCoreCount: 3
       minFreeRamGB: 0.5
       minFreeRamPercent: 20
-    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
+    # defines the minimum number of containers for horizontal autoscaling.
     minContainers: 2
-    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
+    # defines the maximum number of containers for horizontal autoscaling.
     maxContainers: 4
     # optional: create secret env variables
     envSecrets:
@@ -344,11 +348,11 @@ project:
 services:
   - # service name
     hostname: app
-    # service type and version number in nginx@{version} format
-    type: nginx@latest
+    # service type, OS and version number in {os}/nginx@{version} format
+    type: ubuntu/nginx@latest
     # defines the minimum number of containers for horizontal autoscaling
     minContainers: 1
-    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
+    # defines the maximum number of containers for horizontal autoscaling.
     maxContainers: 6
     # optional: create env variables
     envSecrets:

diff --git a/apps/docs/content/nginx/how-to/customize-runtime.mdx b/apps/docs/content/nginx/how-to/customize-runtime.mdx
@@ -20,10 +20,10 @@ You should not include your application code in the custom runtime image, as you
 
 The default Nginx Static runtime environment contains:
 
-- <span>{data.alpine.default}</span>
+- <span>{data.alpine.default}</span> with `alpine/nginx@latest`, or Ubuntu with `ubuntu/nginx@latest`
 - Selected version of Nginx when the runtime service was created
 - [zCLI](/references/cli)
-- Git
+- Git, wget and curl
 
 ### When You Need a Custom Runtime Image
 
@@ -41,6 +41,8 @@ Here are Nginx Static-specific examples of configuring custom runtime images in
     <SetVar name="codeLanguage" value="yaml" />
 <VarCodeBlock codeVar="basicSetupCode" languageVar="codeLanguage" />
 
+Use `sudo apk add` on Alpine and `sudo apt-get install -y` on Ubuntu.
+
 For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).
 
 ## Process and Caching