Skip to main content
Environment variables allow you to configure your application without hardcoding values in your code. They’re essential for managing secrets, feature flags, and environment-specific settings.

​
Adding Environment Variables

You can add environment variables when creating a deployment or update them later.

​
During Deployment Creation

1

Create a new deployment

Start creating a deployment from image or GitHub.
2

Scroll to Environment Variables

Find the Environment Variables section.
3

Add variables

Click Add Variable and enter:
  • Key: The variable name (e.g., DATABASE_URL)
  • Value: The variable value
4

Add more as needed

Repeat for each environment variable your application needs.

​
Updating Existing Deployments

1

Open your deployment

Navigate to the deployment you want to update.
2

Go to Settings

Click on the Settings tab.
3

Edit environment variables

Add, modify, or remove environment variables as needed.
4

Save changes

Click Save. The deployment will restart with the new configuration.
Changing environment variables requires a restart of your pods. Orchard performs a rolling restart to minimize downtime.

​
Common Use Cases

​
Database Connections

DATABASE_URL=postgres://user:pass@db-host:5432/mydb
REDIS_URL=redis://redis-host:6379

​
API Keys and Secrets

API_KEY=sk-xxxxxxxxxxxx
JWT_SECRET=your-secret-key
STRIPE_SECRET_KEY=sk_live_xxxxxxxx

​
Application Configuration

NODE_ENV=production
LOG_LEVEL=info
PORT=3000

​
Feature Flags

FEATURE_NEW_UI=true
ENABLE_ANALYTICS=true

​
Best Practices

Use clear, uppercase names with underscores:Good:
  • DATABASE_URL
  • API_KEY
  • ENABLE_FEATURE_X
Avoid:
  • db
  • key1
  • x
Never commit secrets to your repository. Use environment variables for:
  • API keys
  • Database passwords
  • JWT secrets
  • Third-party service credentials
Keep development and production configurations separate:Development:
DATABASE_URL=postgres://localhost:5432/dev_db
LOG_LEVEL=debug
Production:
DATABASE_URL=postgres://prod-db:5432/prod_db
LOG_LEVEL=info
Keep a list of required environment variables in your README or documentation:
## Required Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| DATABASE_URL | PostgreSQL connection string | postgres://... |
| API_KEY | External API key | sk-xxxx |

​
Referencing Internal Services

When your deployment needs to connect to another service in the same project, use Kubernetes internal DNS: 
# Format: {service-name}.{namespace}.svc.cluster.local:{port}

# Example for a database service named "postgres" in the same project:
DATABASE_HOST=postgres.acme-prod-api.svc.cluster.local
DATABASE_PORT=5432
The namespace follows the pattern: {org-slug}-{workspace-slug}-{project-slug}

​
Variable Interpolation

Environment variable values are stored exactly as entered. Orchard does not perform variable interpolation. If you need to build URLs from components: Instead of: 
# This won't work
DATABASE_URL=postgres://${DB_HOST}:${DB_PORT}/mydb
Use: 
# Store the complete value
DATABASE_URL=postgres://db-host:5432/mydb
Or handle interpolation in your application code.

​
Bulk Operations

​
Importing from .env File

While Orchard doesn’t directly import .env files, you can quickly add multiple variables:
  1. Prepare your variables in key=value format
  2. Add them one by one in the UI
  3. Or use the API for bulk operations

​
Copying Between Deployments

To copy environment variables from one deployment to another:
  1. Note the variables from the source deployment
  2. Create or edit the target deployment
  3. Add the same variables
Be careful when copying variables between environments. Database URLs, API keys, and other secrets should differ between staging and production.

​
Sensitive Values

Environment variables containing sensitive data like passwords and API keys are:
  • Stored securely in the database
  • Not exposed in logs or the UI after creation
  • Passed securely to containers at runtime
While Orchard handles secrets securely, be careful not to log environment variables in your application code, as this could expose sensitive values.

​
Troubleshooting

If your application can’t find an environment variable:
  1. Verify the variable is saved in deployment settings
  2. Check for typos in the variable name
  3. Ensure the deployment has been restarted after changes
  4. Check your application is reading the correct variable name
If your value contains special characters:
  • Quotes, spaces, and special characters are supported
  • No need to escape characters in the UI
  • The value is passed exactly as entered to your container

​
Next Steps

Volumes

Add persistent storage for your data

Services

Expose your deployment to the network