This document provides a complete reference for all environment variables supported by nself v0.3.9+.

Files are loaded in this specific cascade (later overrides earlier):

1. .env.dev - Team development defaults (always loaded first)
2. .env.staging - Staging overrides (only if ENV=staging)
3. .env.prod - Production config (only if ENV=prod)
4. .env.secrets - Sensitive production data (only if ENV=prod)
5. .env - Local overrides (ALWAYS loaded last, highest priority)

All core services default to true for backward compatibility:

All monitoring services default to false:

Support for 16+ email providers. Common configuration:

Supported providers:

• SendGrid
• AWS SES
• Mailgun
• Postmark
• Gmail
• Office365
• Brevo (Sendinblue)
• Resend
• SparkPost
• Mandrill
• Elastic Email
• SMTP2GO
• MailerSend
• Mailchimp Transactional
• Custom SMTP

Support for multiple frontend applications:

Route a custom subdomain to a Docker-internal service (e.g., api.sites.localhost → hasura:8080). These configs survive nself build rebuilds because they are generated deterministically from .env.

Up to 20 routes supported (INTERNAL_ROUTE_1_* through INTERNAL_ROUTE_20_*).

For each route N (1–20):

# .env — route api.sites.localhost → hasura:8080
INTERNAL_ROUTE_1_NAME=api-sites
INTERNAL_ROUTE_1_SUBDOMAIN=api.sites
INTERNAL_ROUTE_1_TARGET=hasura:8080
INTERNAL_ROUTE_1_RATE_ZONE=graphql_api

# Route ws.sites.localhost → a WebSocket service
INTERNAL_ROUTE_2_NAME=ws-sites
INTERNAL_ROUTE_2_SUBDOMAIN=ws.sites
INTERNAL_ROUTE_2_TARGET=myservice:4000
INTERNAL_ROUTE_2_WEBSOCKET=true

After adding routes: nself build && nself restart nginx

Generated config: nginx/sites/internal-<name>.conf

For each custom service N (1-10):

These variables are maintained for backward compatibility but mapped to new names:

These must be set for nself to function:

• PROJECT_NAME - Must be alphanumeric with hyphens
• BASE_DOMAIN - Must be valid domain format

These are auto-generated if not provided:

• All passwords and secrets
• API keys
• JWT secrets
• Admin credentials

These are computed from other variables:

• HASURA_GRAPHQL_DATABASE_URL - Built from PostgreSQL settings
• AUTH_DATABASE_URL - Built from PostgreSQL settings
• STORAGE_DATABASE_URL - Built from PostgreSQL settings

• Ports: Must be 1-65535, not in use
• Passwords: Minimum 12 characters for generated
• Project Name: ^[a-z][a-z0-9-]*$
• Domain: Valid domain or IP format
• Email: Valid email format

1. Never commit .env or .env.secrets to version control
2. Use strong, unique passwords for production
3. Enable 2FA where available
4. Rotate secrets regularly
5. Use environment-specific files

1. Start only needed services
2. Set appropriate resource limits
3. Enable caching where beneficial
4. Use connection pooling
5. Monitor resource usage

1. Use .env.dev for team defaults
2. Keep .env for personal overrides
3. Document custom variables
4. Use consistent naming conventions
5. Validate variables before use

1. Use .env.prod and .env.secrets
2. Enable monitoring services
3. Configure backups
4. Use proper SSL certificates
5. Set resource limits

# Optimized for development
HASURA_GRAPHQL_DEV_MODE=true
HASURA_GRAPHQL_ENABLE_CONSOLE=true
HOT_RELOAD_ENABLED=true
DEBUG_LOGGING=true
SSL_PROVIDER=mkcert
EMAIL_PROVIDER=mailpit

# Production-like but with debugging
HASURA_GRAPHQL_DEV_MODE=false
HASURA_GRAPHQL_ENABLE_CONSOLE=true
HOT_RELOAD_ENABLED=false
DEBUG_LOGGING=true
SSL_PROVIDER=letsencrypt
LETSENCRYPT_STAGING=true

# Optimized for production
HASURA_GRAPHQL_DEV_MODE=false
HASURA_GRAPHQL_ENABLE_CONSOLE=false
HOT_RELOAD_ENABLED=false
DEBUG_LOGGING=false
SSL_PROVIDER=letsencrypt
LETSENCRYPT_STAGING=false
BACKUP_ENABLED=true
MONITORING_ENABLED=true

• Configuration Overview - Configuration guide
• Search Services - Search services configuration
• Backup Guide - Backup configuration
• Troubleshooting - Common issues
• Architecture - System architecture