env replace

Author: vankovap

apps/docs/content/zerops-yaml/specification.mdx

@@ -26,6 +26,10 @@ export const languages = [
 The `zerops.yaml` file is crucial for defining how Zerops should [build and deploy](/features/pipeline) your application.
 Add the `zerops.yaml` file to the **root of your repository** and customize it to suit your application's needs.
 
+:::note Parameter Availability
+Not all parameters are available for every service type. Most parameters work across different runtime services, but some are specific to certain service types (e.g., documentRoot for webserver services, routing for Static services). This documentation covers zerops.yaml configuration for runtime services.
+:::
+
 ---
 
 <GroupCards emoji="🙌" heading="Quick Links to Runtime-Specific Guides" items={languages} />
@@ -39,9 +43,7 @@ zerops:
     run: ...
 ```
 
-- The top-level element is always `zerops`.
-- `setup` contains the **hostname** of your service (must exist in Zerops).
-- Multiple services can be defined in a single `zerops.yaml` (useful for monorepos):
+Multiple services can be defined in a single `zerops.yaml` (useful for monorepos):
 
 ```yaml
 zerops:
@@ -56,7 +58,15 @@ zerops:
 
 Each service configuration requires `build` and `run` sections. An optional `deploy` section can be added for readiness checks.
 
-## Service Inheritance
+## Service Configuration
+
+### setup <Badge type="required" />
+
+Contains the hostname of your service (must exist in Zerops).
+
+```yaml
+setup: my-service
+```
 
 ### extends <Badge type="optional" />
 
@@ -67,26 +77,22 @@ zerops:
   - setup: base
     build:
       buildCommands:
-        - echo "hello"
-      deployFiles: ./
+        - npm run build
+      deployFiles: ./dist
     run:
-      start: server run
+      start: npm start
 
   - setup: prod
     extends: base
     run:
-      crontab:
-        - command: xyz
-          allContainers: false
-          timing: "* * * * *"
+      envVariables:
+        NODE_ENV: production
 
   - setup: dev
     extends: base
     run:
-      crontab:
-        - command: different command
-          allContainers: false
-          timing: "* * * * *"
+      envVariables:
+        NODE_ENV: development
 ```
 
 When using `extends`:
@@ -294,10 +300,11 @@ Defines the port number on which your application listens. Must be between *10*
 #### protocol <Badge type="optional" />
 Specifies the network protocol to use:
 - Allowed values: `TCP` *(default)* or `UDP`
+
 #### httpSupport <Badge type="optional" />
 Indicates whether the port is running a web server:
-- Default value: `true`
-- Set to `false` if a web server isn't running on the port
+- Default value: `false`
+- Set to `true` if a web server is running on the port
 - Only available with TCP protocol
 - Used by Zerops for [public access](/features/access) configuration
 
@@ -330,7 +337,7 @@ run:
 
 ### startCommands <Badge type="optional" />
 
-Defines start commands 
+Defines start commands.
 
 Unlike `start`, you can define multiple commands that starts their own processes.
 
@@ -341,7 +348,6 @@ run:
     - command: npm run start:prod
       name: server
     # start the replication
-    
     - command: litestream replicate -config=litestream.yaml
       name: replication
       # restore the database on container init
@@ -373,6 +379,140 @@ Defines environment variables for the runtime environment.
         DB_PASS: ${db_password}
 ```
 
+### envReplace <Badge type="optional" />
+
+Automatically replaces environment variable placeholders in your static files with their actual values during deployment.
+
+```yaml
+run:
+  envReplace:
+    delimiter: "%%"
+    target:
+      - config/jwt/public.pem
+      - config/jwt/private.pem
+      - ./config/
+```
+
+Available parameters:
+
+#### delimiter <Badge type="required" />
+Characters that wrap your variable names in placeholders (e.g., `%%` means placeholders look like `%%VARIABLE%%`).
+- Type: `string` or `array of strings`
+- Supports multiple delimiters simultaneously
+
+#### target <Badge type="required" />
+Files or directories to process for variable replacement.
+- Type: `string` or `array of strings`
+- Can be specific files or directories with glob patterns
+- **Important**: Directory paths like `./` only process files in that directory, not subdirectories. For recursive processing, specify each subdirectory explicitly
+
+**How it works:**
+1. Define placeholders in your files using the specified delimiters
+2. Set environment variables with matching names
+3. During deployment, Zerops finds and replaces placeholders with actual values
+
+**Example usage:**
+
+```yaml
+run:
+  envReplace:
+    delimiter: "%%"
+    target:
+      - ./config/
+      - ./templates/
+      - ./              # Only processes files in root, not subdirectories
+```
+
+File content before replacement:
+```
+# config/jwt/public.pem
+%%JWT_PUBLIC_KEY_CONTENT%%
+```
+
+Environment variable:
+```
+JWT_PUBLIC_KEY_CONTENT=-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----
+```
+
+The placeholder gets replaced with the actual JWT public key during deployment.
+
+:::warning
+When using `./` as target, only files directly in the root directory are processed. Subdirectories are ignored for performance reasons. To process subdirectories, specify each one explicitly in the target array.
+:::
+
+### routing <Badge type="optional" />
+
+Configures URL routing, redirects, and HTTP headers (primarily for Static services).
+
+```yaml
+run:
+  routing:
+    root: /custom/root
+    cors: "'*' always"
+    redirects:
+      - from: /old-path
+        to: /new-path
+        status: 301
+    headers:
+      - for: "/*"
+        values:
+          X-Frame-Options: "'DENY'"
+```
+
+Available parameters:
+
+#### root <Badge type="optional" />
+Sets a custom root directory for the service.
+- Type: `string`
+
+#### cors <Badge type="optional" />
+Enables CORS headers for cross-origin requests.
+- Type: `string`
+- Sets `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`, and `Access-Control-Expose-Headers`
+- Special case: `"*"` is automatically converted to `'*'`
+
+#### redirects <Badge type="optional" />
+Defines URL redirects and rewrites.
+- Type: `array of objects`
+- Each redirect object supports:
+  - **from** <Badge type="required" /> - Source path to match (supports wildcards with `*`)
+  - **to** <Badge type="required" /> - Destination path
+  - **status** <Badge type="optional" /> - HTTP status code (required for absolute URLs)
+  - **preservePath** <Badge type="optional" /> - Preserve path after wildcard match
+  - **preserveQuery** <Badge type="optional" /> - Preserve query parameters
+
+#### headers <Badge type="optional" />
+Sets custom HTTP headers for specific paths.
+- Type: `array of objects`
+- Each header object supports:
+  - **for** <Badge type="required" /> - Path pattern to match (supports wildcards)
+  - **values** <Badge type="required" /> - Object with header name/value pairs
+
+**Example usage:**
+
+```yaml
+run:
+  routing:
+    cors: "'*' always"
+    redirects:
+      # Permanent redirect
+      - from: /old-page
+        to: /new-page
+        status: 301
+      # Wildcard redirect with path preservation
+      - from: /blog/*
+        to: /articles/
+        preservePath: true
+        status: 302
+    headers:
+      - for: "/*"
+        values:
+          X-Frame-Options: "'DENY'"
+          Content-Security-Policy: '"default-src ''self''"'
+```
+
 ### healthCheck <Badge type="optional" />
 
 Defines a health check for your application.
@@ -427,19 +567,36 @@ Health checks continuously monitor your running application, while readiness che
 
 ### crontab <Badge type="optional" />
 
-  Defines scheduled commands to run as cron jobs within a service.
+Defines scheduled commands to run as cron jobs within a service.
 
-  ```yaml
-  run:
-    crontab:
-      - command: "date >> /var/log/cron.log"
-        timing: "0 * * * *"
-  ```
+```yaml
+run:
+  crontab:
+    - command: "date >> /var/log/cron.log"
+      timing: "0 * * * *"
+      allContainers: false
+```
 
 Setup cron jobs. See [examples](/zerops-yaml/cron).
 
 ## Deploy Configuration
 
+### temporaryShutdown <Badge type="optional" />
+
+Controls the container replacement order during deployment.
+
+```yaml
+deploy:
+  temporaryShutdown: true
+```
+
+- Type: `boolean`
+- Default: `false`
+
+**When `false` (default):** New containers are started before old containers are removed, ensuring zero-downtime deployment.
+
+**When `true`:** Old containers are removed before new containers are started, causing temporary downtime but using fewer resources during deployment.
+
 ### readinessCheck <Badge type="optional" />
 
 Defines a readiness check for your application. Requires either `httpGet` object or `exec` object.
@@ -480,4 +637,4 @@ Unlike health checks which run continuously, readiness checks only run during de
 For more detailed information on specific configurations, refer to the runtime-specific guides linked at the beginning of this document.
 :::
 
----
+*Need help? Join our [Discord community](https://discord.gg/zeropsio).*