Environment variables

Configure environment variables for your containers, including encrypted secrets.

Overview

Odysseus supports two types of environment variables:

• Clear: Plaintext values stored in deploy.yml
• Secret: Sensitive values stored in an encrypted file

env:
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: "true"
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY

Clear variables

Use env.clear for non-sensitive configuration:

env:
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: "true"
    RAILS_SERVE_STATIC_FILES: "true"
    WEB_CONCURRENCY: "2"

These values are stored directly in your configuration file.

Secret variables

Use env.secret for sensitive values:

env:
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY
    - REDIS_URL
    - AWS_ACCESS_KEY_ID
    - AWS_SECRET_ACCESS_KEY

secrets_file: secrets.yml.enc

Secret values are loaded from an encrypted file at deploy time.

Creating secrets

1. Generate a master key:

odysseus secrets generate-key

This outputs a key. Store it securely (e.g., password manager, CI secrets).

2. Create a secrets file:

# secrets.yml
DATABASE_URL: postgres://user:pass@localhost/myapp
RAILS_MASTER_KEY: abc123def456
REDIS_URL: redis://localhost:6379

3. Encrypt the secrets:

ODYSSEUS_MASTER_KEY=your-key odysseus secrets encrypt \
  --input secrets.yml \
  --file secrets.yml.enc

4. Commit secrets.yml.enc and delete secrets.yml:

rm secrets.yml
git add secrets.yml.enc
git commit -m "Add encrypted secrets"

Using secrets

Set the master key in your environment:

export ODYSSEUS_MASTER_KEY=your-key
odysseus deploy

Or pass it directly:

ODYSSEUS_MASTER_KEY=your-key odysseus deploy

See Secrets management for more details.

Variable precedence

Environment variables are applied in this order:

1. Container's built-in variables
2. Clear variables from deploy.yml
3. Secret variables from encrypted file

Later sources override earlier ones.

Per-role variables

Currently, environment variables apply to all roles. To use different values per role, use conditional logic in your application:

# In your application
if ENV['ROLE'] == 'worker'
  # Worker-specific configuration
end

Set a role indicator in clear variables:

servers:
  web:
    hosts:
      - app.example.com
  jobs:
    hosts:
      - worker.example.com
    cmd: ROLE=worker bundle exec sidekiq

Common patterns

Rails applications

env:
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: "true"
    RAILS_SERVE_STATIC_FILES: "true"
    WEB_CONCURRENCY: "2"
    MALLOC_ARENA_MAX: "2"
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY
    - REDIS_URL
    - SECRET_KEY_BASE

Node.js applications

env:
  clear:
    NODE_ENV: production
    PORT: "3000"
  secret:
    - DATABASE_URL
    - SESSION_SECRET
    - API_KEY

Python applications

env:
  clear:
    PYTHON_ENV: production
    WORKERS: "4"
  secret:
    - DATABASE_URL
    - SECRET_KEY
    - SENTRY_DSN

Debugging variables

Check what variables are set in a running container:

odysseus app exec your-server --command "env | sort"

Or start a shell:

odysseus app shell your-server
# Then inside the container:
env | grep RAILS