Environment variables and secrets

Use environment variables for configuration that changes between deployments or contains secrets. Common examples include database URLs, application keys, API credentials, and public frontend configuration.

Add a service variableCopy Anchor Link

1. Open the service's Environment page.
2. Select Add variable and enter its key and value.
3. Save the variable, then deploy the service.

Read the value using your framework's environment API:

const databaseUrl = process.env.DATABASE_URL;

import os

database_url = os.environ["DATABASE_URL"]

Use a required lookup for a secret your app cannot operate without. Silently falling back to a development database or default password can make a deployment appear healthy while using the wrong data.

Share configuration with environment groupsCopy Anchor Link

Create an Environment Group from the workspace navigation and add the variables or secret files that related services should share. Link the group from each service's Environment page. Groups can be scoped to an environment, so use separate groups for production and test credentials.

Service-level values override matching group values. Avoid defining the same key in several linked groups; if an override is intentional, put it directly on the service so its precedence is clear. Linked-service references cannot use a key already defined by a variable; remove the duplicate before deploying.

Group edits apply to future deployments. Deploy each linked service that must receive an updated value.

Groups linked to protected services require owner or admin access. A service that inherits protected configuration keeps that restriction even after unlinking the group, because its current or retained deployments can contain the copied values. The same rule covers protected connection references and preview copies. See environment protection.

Mount a secret fileCopy Anchor Link

Under Secret Files, add a filename and its contents. At runtime, the file is mounted read-only at:

/etc/secrets/<filename>

For example, a file named credentials.json is available at /etc/secrets/credentials.json. Configure your application to read that path. Do not write back to the mounted file or assume it exists on your laptop.

Secret files are runtime mounts. For a Docker build that needs a variable as a secret, use the supported BuildKit secret mount rather than copying private files into the image.

Build-time and runtime valuesCopy Anchor Link

Railpack receives configured variables during the build and the application receives its deployment's variables at runtime. Variables compiled into a frontend become public: NEXT_PUBLIC_*, VITE_*, and similar mechanisms expose their values in files delivered to the browser.

Never put a database password, private API key, or Openstead API token into a browser-exposed variable. Keep it in a backend service and expose only the necessary application endpoint.

Openstead sets runtime PORT from the service's port setting. Configure that setting to match your server rather than using a competing PORT value in a shared group.

Rotate secrets carefullyCopy Anchor Link

Add the new credential, deploy, and verify the application before revoking the old one at its provider. Some rotations require a period in which both credentials remain valid.

Deployment records retain their captured environment for release recovery. A rollback can restore older secret values. If a compromised credential has been revoked, deploy compatible code with the current environment rather than blindly restoring the old snapshot.

Avoid logging secrets. Redaction helps with recognized values, but it cannot make arbitrary transformed or application-generated sensitive output safe to publish.