Environment Variables

Environment variables let you configure your services with secrets, API keys, and other settings without hardcoding them in your source code.

Variable scoping

Stackpad has three levels of environment variables. Each level overrides the one above it:

Project variables       (shared across all environments and services)
  ↓ overridden by
Environment variables   (shared across all services in one environment)
  ↓ overridden by
Service variables       (specific to a single service)

Project-level variables

Apply to every service in every environment. Set them in your project’s Environment Variables page under the All environments tab.

Use project-level variables for values that are the same everywhere:

• NODE_ENV=production
• Shared API keys used by multiple services
• Feature flags

Environment-level variables

Apply to all services within a specific environment (e.g. production vs staging). Set them by selecting an environment tab on the Environment Variables page.

Use environment-level variables when you need different values per environment:

• API_URL=https://api.example.com in production
• API_URL=https://staging-api.example.com in staging
• Different third-party API keys per environment

Service-level variables

Apply to a single service only. Set them in the service’s detail page under the Env Vars tab.

Use service-level variables for values unique to one service:

• PORT=3000
• Service-specific API keys
• Configuration specific to that container

Override example

If you set the same variable at multiple levels:

Level	API_URL value
Project	https://api.example.com
Environment (staging)	https://staging.example.com
Service (web)	— (not set)

The web service in the staging environment receives https://staging.example.com (environment overrides project). In production, it receives https://api.example.com (project-level, since no environment override exists).

Auto-injected variables

Stackpad automatically generates and injects connection strings when you add database or cache services to a project.

What gets injected

Service type	Variable	Format
PostgreSQL	DATABASE_URL	postgresql://user:pass@postgres:5432/dbname
MariaDB	MYSQL_URL	mysql://user:pass@mariadb:3306/dbname
Redis	REDIS_URL	redis://redis:6379
Valkey	REDIS_URL	redis://valkey:6379

These variables are injected into all sibling services in the same project. They use private network DNS names, so they work automatically without configuration.

When auto-injected variables take effect

Auto-injected variables are written to the database immediately when the service is created. However:

Caution

If you add a database to a project that already has a running web service, the web service needs to be redeployed to pick up the new DATABASE_URL. The variable exists, but the running container doesn’t see it until it restarts.

Click Redeploy on your web service after adding a database.

Auto-injected variables appear in the dashboard with a lock icon and the label “auto-injected”. You can’t edit or delete them — they’re managed by Stackpad.

Multiple databases

If you add both PostgreSQL and MariaDB to the same project, both DATABASE_URL and MYSQL_URL are injected into your web services.

Adding variables

One at a time

On the environment variables page or service env vars tab:

1. Enter the key (e.g. STRIPE_SECRET_KEY)
2. Enter the value (masked by default)
3. Click Add

Bulk paste from .env file

Click Paste .env to switch to bulk mode:

1. Paste your .env file contents into the textarea
2. Stackpad shows a summary: how many new variables will be imported and how many are skipped (already exist)
3. Click Import to add them all

This is the fastest way to migrate environment variables from another platform.

Build-time vs. runtime variables

By default, environment variables are available at both build time and runtime:

• Build time — injected as Docker build arguments. Available during npm run build, useful for NEXT_PUBLIC_* variables in Next.js
• Runtime — available as process.env.* when your container runs

Tip

Next.js NEXT_PUBLIC_* variables are embedded into the JavaScript bundle at build time. If you change them, you need to rebuild — a runtime-only change won’t work for these.

Encryption and security

• All variable values are encrypted using AES-256-GCM before storage
• Values are write-only — after creation, the dashboard shows the key name but never the value
• To update a value, you replace it entirely
• Auto-injected database passwords are generated as 32-character random strings

Updating variables

Note

Changing an environment variable does not automatically redeploy your service. The change is saved immediately, but the running container keeps the old value until the next deploy.

To apply changes immediately, click Redeploy on the service.

What’s next?

• Connecting services — how services discover each other via private networking
• PostgreSQL — add a database and use auto-injected DATABASE_URL
• Git push deploy — how deployments work