Environment Cascade & Cascading Overrides

Understand how nself's environment variable system works and how to manage configuration across development, staging, and production.

Overview

nself uses a cascading override system where configuration files layer on top of each other. Each file overrides the previous one, allowing for:

Shared defaults (committed to git)
Local customization (on your machine only)
Environment-specific overrides (staging vs production)
Secrets management (never in git)

The Cascade Order

Configuration is loaded in this exact order. Later files override earlier files:

.env.dev             (1. Base - Committed to git)
    ↓
.env.local           (2. Local - On your machine only)
    ↓
.env.staging         (3. Staging - On staging server only)
    ↓
.env.prod            (4. Production - On prod server only)
    ↓
.env.secrets         (5. Secrets - Ultra-sensitive, server only)
    ↓
.env.computed        (6. Computed - Auto-generated, never edit)

File Purposes

1. .env.dev (Shared Defaults)

Purpose: Base configuration used by all developers.

Properties:

Committed to git
Shared by entire team
Contains safe default values
No secrets or sensitive data

Example:

PROJECT_NAME=my-app
ENV=dev
BASE_DOMAIN=localhost
POSTGRES_DB=myapp_dev
HASURA_GRAPHQL_ENABLE_CONSOLE=true

2. .env.local (Developer Overrides)

Purpose: Your personal machine customizations.

Properties:

Gitignored (never committed)
Only on your machine
Overrides .env.dev
Can contain personal secrets

Example:

# You want to use a different Postgres password
POSTGRES_PASSWORD=my-super-secret-local-password

# You want to enable Redis locally
REDIS_ENABLED=true

Result: Your machine uses your password, all other values from .env.dev.

3. .env.staging (Staging Server)

Purpose: Configuration specific to the staging environment.

Properties:

On staging server only (not on developer machines)
Overrides .env.dev and .env.local
Staging-specific values (staging database, staging API keys)

Example:

# Staging database with more data
POSTGRES_PASSWORD=staging-db-password

# Staging Hasura admin secret
HASURA_GRAPHQL_ADMIN_SECRET=staging-secret-123

# Enable monitoring on staging
MONITORING_ENABLED=true

Access: Senior developers via SSH to staging server.

4. .env.prod (Production Server)

Purpose: Production-specific configuration.

Properties:

On production server only
Overrides everything above
Production URLs, API keys, feature flags

Example:

# Production database
POSTGRES_PASSWORD=prod-database-password

# Production domain
BASE_DOMAIN=myapp.com

# Production Hasura secret
HASURA_GRAPHQL_ADMIN_SECRET=prod-secret-xyz

Access: Lead developers only via SSH to production.

5. .env.secrets (Secrets Only)

Purpose: Ultra-sensitive credentials, generated on server.

Properties:

Generated on server at setup time
Never in git (ever)
Only on production server
Encrypted if stored at rest

Example:

# Master encryption key
ENCRYPTION_KEY=long-random-string-from-server

# Database root password
POSTGRES_ROOT_PASSWORD=ultra-secret-generated-key

# JWT signing key
JWT_SECRET=another-generated-secret

Access: Lead developers only, synced via secure SSH.

6. .env.computed (Auto-Generated)

Purpose: Computed values generated during nself build.

Properties:

Auto-generated by nself (never edit)
Contains derived values
Based on other environment variables

Example:

# Generated from POSTGRES credentials
DATABASE_URL=postgresql://postgres:password@postgres:5432/myapp_db

# Generated from PROJECT_NAME
DOCKER_NETWORK=my-app_network

# Generated service hosts
POSTGRES_HOST=postgres
HASURA_HOST=hasura

Loading Order in Code

When nself starts, it loads variables in order:

#!/bin/bash

# Load .env.dev first (shared defaults)
if [ -f .env.dev ]; then
  source .env.dev
fi

# Load .env.local second (your overrides)
if [ -f .env.local ]; then
  source .env.local
fi

# Load environment-specific (staging, prod, etc)
if [ -f .env.${ENV} ]; then
  source .env.${ENV}
fi

# Load production secrets last (if they exist)
if [ -f .env.secrets ]; then
  source .env.secrets
fi

# Auto-generate computed values
source .env.computed

Practical Example

Project Setup

Starting configuration:

File: .env.dev (committed to git)

PROJECT_NAME=my-app
ENV=dev
BASE_DOMAIN=localhost
POSTGRES_DB=myapp_db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change-me
HASURA_GRAPHQL_ADMIN_SECRET=change-me
REDIS_ENABLED=false
MONITORING_ENABLED=false

File: .env.local (on developer's machine, gitignored)

# Developer wants local Redis for caching
REDIS_ENABLED=true

# Developer uses different password
POSTGRES_PASSWORD=my-local-password-456
HASURA_GRAPHQL_ADMIN_SECRET=my-local-secret-789

What Actually Gets Used?

When you run nself start on your local machine:

Variable	Source	Value
`PROJECT_NAME`	.env.dev	`my-app`
`ENV`	.env.dev	`dev`
`BASE_DOMAIN`	.env.dev	`localhost`
`POSTGRES_DB`	.env.dev	`myapp_db`
`POSTGRES_USER`	.env.dev	`postgres`
`POSTGRES_PASSWORD`	.env.local (override)	`my-local-password-456`
`HASURA_GRAPHQL_ADMIN_SECRET`	.env.local (override)	`my-local-secret-789`
`REDIS_ENABLED`	.env.local (override)	`true`
`MONITORING_ENABLED`	.env.dev	`false`

On Staging Server

The staging server doesn't have .env.local. It loads:

File: .env.dev (from git)

PROJECT_NAME=my-app
POSTGRES_PASSWORD=change-me
# ...

File: .env.staging (only on staging server)

POSTGRES_PASSWORD=staging-db-password-xyz
BASE_DOMAIN=staging.myapp.com
MONITORING_ENABLED=true

Result on staging:

Variable	Source	Value
`POSTGRES_PASSWORD`	.env.staging	`staging-db-password-xyz`
`BASE_DOMAIN`	.env.staging	`staging.myapp.com`
`MONITORING_ENABLED`	.env.staging	`true`
Other vars	.env.dev	(defaults)

Developer Access Levels

nself supports role-based environment access:

Developer (Junior)

Access: .env.dev + .env.local only

Can develop locally but cannot see staging/production secrets.

nself env switch local          # Works (they have .env.local)
nself sync pull staging         # Fails (no SSH access to staging)

Senior Developer

Access: .env.dev, .env.local, + .env.staging

Can test on staging server without accessing production.

nself env switch local          # Works
nself sync pull staging         # Works (SSH access to staging)
nself sync pull prod            # Fails (no SSH access to prod)

Lead Developer

Access: All files including .env.secrets

Full access to production for emergencies and critical tasks.

nself env switch local          # Works
nself sync pull staging         # Works
nself sync pull prod            # Works (SSH access to prod)
nself sync pull secrets         # Works (access to .env.secrets)

Syncing Configuration Across Machines

Pull Staging Configuration

Senior developers can pull staging configuration to their local machine:

# Pull .env.staging from staging server via SSH
nself sync pull staging

# This creates .env.staging locally (gitignored)
# Now you can test staging config locally

Pull Production Configuration

Lead developers only:

# Pull .env.prod from production server
nself sync pull prod

# Pull .env.secrets (master credentials)
nself sync pull secrets

Push Configuration

Update configuration on remote:

# Sync your .env changes to staging
nself sync push staging

# Sync to production (Lead Dev only)
nself sync push prod

Gitignore for Environment Files

Your .gitignore should include:

# Local overrides
.env.local

# Environment-specific (don't commit staging/prod)
.env.staging
.env.prod

# Secrets (NEVER commit)
.env.secrets

# Computed values (auto-generated)
.env.computed

Only .env.dev should be committed to git.

# Good - only base config in git
git add .env.dev
git commit -m "feat: update base configuration"

# BAD - never do this
git add .env.secrets  # ❌ NEVER!
git add .env.prod     # ❌ NEVER!

Common Workflows

1. Local Development

# Edit .env.dev for shared changes
vim .env.dev
git add .env.dev
git commit -m "update base config"
git push

# Edit .env.local for personal changes
vim .env.local  # Not committed
# No git commands needed

2. Testing Staging Config Locally

# Pull staging config
nself sync pull staging

# Switch to staging config for testing
nself env switch staging

# Run tests
nself build
nself start

# Switch back to local
nself env switch local

3. Emergency Production Fix

# Lead dev only
nself sync pull prod

# Make emergency change
vim .env.prod

# Apply immediately
nself build
nself restart

# Push change to remote
nself sync push prod

4. Adding New Variable to All Environments

As a developer:

# Add to .env.dev (shared)
echo "NEW_VAR=value" >> .env.dev
git add .env.dev
git commit -m "add NEW_VAR to configuration"
git push

# Tell Sr Dev and Lead Dev they need to add to their environment files

As Sr Dev:

# Add staging value
echo "NEW_VAR=staging-value" >> .env.staging
nself sync push staging

As Lead Dev:

# Add production value
echo "NEW_VAR=prod-value" >> .env.prod
nself sync push prod

Troubleshooting

Wrong Value in Use

Problem: You set a value in .env.local but it's not being used.

Solution: Check the cascade order. Later files override earlier ones.

# Check which file has the value
grep "POSTGRES_PASSWORD" .env.dev
grep "POSTGRES_PASSWORD" .env.local

# The .env.local value should be used

Staging Config Not Syncing

Problem: Changed .env.staging on staging server but not seeing changes locally.

Solution: Pull the latest config:

nself sync pull staging

Secrets File Missing

Problem: .env.secrets doesn't exist on production server.

Solution: Generate it:

# On production server
nself config generate-secrets

# This creates .env.secrets with generated values

Port Conflict Between Environments

Problem: Local dev uses port 8080, but staging also tries to use 8080.

Solution: Use different ports in each environment:

# .env.dev
NGINX_PORT=8080

# .env.staging
NGINX_PORT=8081

# .env.prod
NGINX_PORT=443  # HTTPS only

Best Practices

Keep .env.dev minimal - Only shared defaults
Never commit .env.local - Add to .gitignore
Never commit secrets - Use .env.secrets on servers
Use meaningful defaults - change-me for passwords
Document required variables - List in README
Rotate secrets regularly - Especially in production
Audit changes - Use nself audit logs config

Next Steps

Build Configuration - How build uses env files
Secrets Management - Secure secret handling
Deployment Guide - Deploying across environments

Key Takeaway: The cascading environment system lets you have one source of truth (git) while allowing safe local development and secure production secrets. Understand the order and you'll never have configuration issues.

CASCADING OVERRIDES - nself-org/cli GitHub Wiki

Environment Cascade & Cascading Overrides

Overview

The Cascade Order

File Purposes

1. .env.dev (Shared Defaults)

2. .env.local (Developer Overrides)

3. .env.staging (Staging Server)

4. .env.prod (Production Server)

5. .env.secrets (Secrets Only)

6. .env.computed (Auto-Generated)

Loading Order in Code

Practical Example

Project Setup

What Actually Gets Used?

On Staging Server

Developer Access Levels

Developer (Junior)

Senior Developer

Lead Developer

Syncing Configuration Across Machines

Pull Staging Configuration

Pull Production Configuration

Push Configuration

Gitignore for Environment Files

Common Workflows

1. Local Development

2. Testing Staging Config Locally

3. Emergency Production Fix

4. Adding New Variable to All Environments

Troubleshooting

Wrong Value in Use

Staging Config Not Syncing

Secrets File Missing

Port Conflict Between Environments

Best Practices

Next Steps

⚠️ GitHub.com Fallback ⚠️

CASCADING OVERRIDES - nself-org/cli GitHub Wiki

Environment Cascade & Cascading Overrides

Overview

The Cascade Order

File Purposes

1. .env.dev (Shared Defaults)

2. .env.local (Developer Overrides)

3. .env.staging (Staging Server)

4. .env.prod (Production Server)

5. .env.secrets (Secrets Only)

6. .env.computed (Auto-Generated)

Loading Order in Code

Practical Example

Project Setup

What Actually Gets Used?

On Staging Server

Developer Access Levels

Developer (Junior)

Senior Developer

Lead Developer

Syncing Configuration Across Machines

Pull Staging Configuration

Pull Production Configuration

Push Configuration

Gitignore for Environment Files

Common Workflows

1. Local Development

2. Testing Staging Config Locally

3. Emergency Production Fix

4. Adding New Variable to All Environments

Troubleshooting

Wrong Value in Use

Staging Config Not Syncing

Secrets File Missing

Port Conflict Between Environments

Best Practices

Next Steps

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️