Environment Variables Reference

This comprehensive reference covers all environment variables available in nself. These variables allow you to customize every aspect of your deployment without modifying code.

Security Note

Never commit environment files to version control. Use strong, unique passwords for all services in production.

Core Project Settings

Basic Configuration

VariableDefaultDescription
PROJECT_NAMEnself-backendName of your project, used in Docker container names
ENVdevEnvironment type: dev, prod (v0.2.1+)
ENVIRONMENTdevelopmentLegacy environment variable (deprecated, use ENV)
DEBUGtrueEnable debug mode (development only)
LOG_LEVELinfoLogging level: debug, info, warn, error

Domain and Network

VariableDefaultDescription
DOMAINlocal.nself.orgPrimary domain for your deployment
SUBDOMAIN_PREFIX(empty)Prefix for service subdomains
SSL_MODEnoneSSL provider (letsencrypt, custom, self-signed, none)
FORCE_SSLfalseRedirect HTTP to HTTPS

PostgreSQL Database

Connection Settings

VariableDefaultDescription
POSTGRES_DBpostgresDatabase name
POSTGRES_USERpostgresDatabase user
POSTGRES_PASSWORDpostgresDatabase password (⚠️ Change in production)
POSTGRES_HOSTpostgresDatabase host
POSTGRES_PORT5432Database port

Performance Settings

VariableDefaultDescription
POSTGRES_MAX_CONNECTIONS100Maximum concurrent connections
POSTGRES_SHARED_BUFFERS128MBShared buffer pool size
POSTGRES_EFFECTIVE_CACHE_SIZE4GBEffective cache size for query planning
POSTGRES_WORK_MEM4MBMemory for query operations
POSTGRES_MAINTENANCE_WORK_MEM64MBMemory for maintenance operations

Backup and Maintenance

VariableDefaultDescription
DB_AUTO_MIGRATEfalseAutomatically run migrations on startup
DB_SEED_ON_INITtrueRun seeding scripts on first startup
DB_ENV_SEEDStrueUse environment-specific seed directories (v0.2.1+)
BACKUP_ENABLEDfalseEnable automated backups
BACKUP_SCHEDULE0 2 * * *Backup schedule (cron format)
BACKUP_RETENTION7Number of backups to retain

Hasura GraphQL Engine

Core Settings

VariableDefaultDescription
HASURA_GRAPHQL_ADMIN_SECRETmyadminsecretAdmin secret for console access (⚠️ Change in production)
HASURA_GRAPHQL_JWT_SECRET{"type":"HS256","key":"secret"}JWT configuration for authentication
HASURA_GRAPHQL_ENABLE_CONSOLEtrueEnable web console (disable in production)
HASURA_GRAPHQL_DEV_MODEtrueEnable development mode features
HASURA_GRAPHQL_UNAUTHORIZED_ROLEanonymousDefault role for unauthenticated users

Performance and Limits

VariableDefaultDescription
HASURA_GRAPHQL_QUERY_DEPTH_LIMIT10Maximum query depth allowed
HASURA_GRAPHQL_NODE_LIMIT100Maximum nodes per query
HASURA_GRAPHQL_BATCH_SIZE100Maximum batch size for mutations
HASURA_GRAPHQL_PG_CONNECTIONS50PostgreSQL connection pool size
HASURA_GRAPHQL_PG_TIMEOUT180PostgreSQL connection timeout (seconds)

Logging and Monitoring

VariableDefaultDescription
HASURA_GRAPHQL_LOG_LEVELinfoLogging level
HASURA_GRAPHQL_ENABLED_LOG_TYPESstartup,http-logTypes of logs to enable
HASURA_GRAPHQL_STRUCTURED_LOGGINGtrueEnable structured JSON logging

Redis Cache

Connection Settings

VariableDefaultDescription
REDIS_ENABLEDtrueEnable Redis service
REDIS_HOSTredisRedis host
REDIS_PORT6379Redis port
REDIS_PASSWORD(empty)Redis password (set for production)
REDIS_DB0Redis database number

Performance Settings

VariableDefaultDescription
REDIS_MAXMEMORY256MBMaximum memory usage
REDIS_MAXMEMORY_POLICYallkeys-lruEviction policy when memory limit is reached
REDIS_TCP_KEEPALIVE300TCP keepalive timeout
REDIS_TIMEOUT0Client connection timeout (0 = no timeout)

MinIO Storage

Authentication

VariableDefaultDescription
MINIO_ENABLEDtrueEnable MinIO service
MINIO_ROOT_USERminioadminMinIO admin username (⚠️ Change in production)
MINIO_ROOT_PASSWORDminioadminMinIO admin password (⚠️ Change in production)
MINIO_DEFAULT_BUCKETSuploads,avatars,documentsBuckets to create on startup

Network and Storage

VariableDefaultDescription
MINIO_API_PORT9000MinIO API port
MINIO_CONSOLE_PORT9001MinIO web console port
MINIO_DATA_DIR./storage/minio/dataData storage directory
MINIO_CONFIG_DIR./storage/minio/configConfiguration directory

Microservices Configuration

NestJS Services

VariableDefaultDescription
NESTJS_SERVICES(empty)Comma-separated list of NestJS services
NESTJS_VERSION10.xNestJS framework version
NESTJS_PORT_START3000Starting port for NestJS services
NESTJS_CORS_ENABLEDtrueEnable CORS for NestJS services

Python Services

VariableDefaultDescription
PYTHON_SERVICES(empty)Comma-separated list of Python services
PYTHON_VERSION3.11Python version to use
PYTHON_PORT_START8000Starting port for Python services
PYTHON_FRAMEWORKfastapiPython framework: fastapi, flask, django

Go Services

VariableDefaultDescription
GOLANG_SERVICES(empty)Comma-separated list of Go services
GOLANG_VERSION1.21Go version to use
GOLANG_PORT_START8080Starting port for Go services
GOLANG_CGO_ENABLED0Enable/disable CGO

SSL/TLS Configuration

Certificate Settings

VariableDefaultDescription
SSL_MODEnoneSelect SSL provider
SSL_CERT_PATH/etc/ssl/certs/server.crtSSL certificate file path
SSL_KEY_PATH/etc/ssl/private/server.keySSL private key file path
FORCE_SSLfalseRedirect HTTP to HTTPS

Let's Encrypt

VariableDefaultDescription
LETSENCRYPT_EMAILadmin@example.comEmail for Let's Encrypt registration
LETSENCRYPT_DOMAINSexample.com,api.example.comDomains for SSL certificates

Resource Limits

Memory Limits

VariableDefaultDescription
POSTGRES_MEMORY_LIMIT1024MBPostgreSQL memory limit
HASURA_MEMORY_LIMIT512MBHasura memory limit
REDIS_MEMORY_LIMIT256MBRedis memory limit
MINIO_MEMORY_LIMIT512MBMinIO memory limit

CPU Limits

VariableDefaultDescription
POSTGRES_CPU_LIMIT1.0PostgreSQL CPU limit (cores)
HASURA_CPU_LIMIT0.5Hasura CPU limit (cores)
REDIS_CPU_LIMIT0.3Redis CPU limit (cores)
MINIO_CPU_LIMIT0.5MinIO CPU limit (cores)

Optional Services

Development Services

VariableDefaultDescription
MAILHOG_ENABLEDtrueEnable email testing service
NHOST_DASHBOARD_ENABLEDtrueEnable Nhost dashboard
ADMINER_ENABLEDfalseEnable database browser
SWAGGER_ENABLEDtrueEnable API documentation

Background Services

VariableDefaultDescription
BULLMQ_WORKERS(empty)Comma-separated list of BullMQ workers
FUNCTIONS_ENABLEDfalseEnable serverless functions
FUNCTIONS_RUNTIMEnodeFunctions runtime: node, python, go

Best Practices

Security

  • Change Default Passwords: Never use default passwords in production
  • Use Strong Secrets: Generate long, random secrets for JWT and admin access
  • Environment Separation: Use different credentials for each environment
  • Secure Storage: Use environment variable management tools in production

Performance

  • Resource Allocation: Set appropriate memory and CPU limits based on usage
  • Connection Pooling: Configure database connection pools properly
  • Caching: Enable and configure Redis caching for better performance
  • Monitoring: Enable metrics collection and monitoring

Configuration Management

  • Version Control: Never commit .env files to version control
  • Templates: Keep .env.example updated with all available options
  • Documentation: Document custom environment variables
  • Validation: Validate configuration before deployment

Examples

Development Configuration

# .env.local - Development
PROJECT_NAME=my-app
ENV=dev  # New in v0.2.1
DEBUG=true

# Database
POSTGRES_PASSWORD=dev_password
POSTGRES_DB=myapp_dev

# Services
REDIS_ENABLED=true
MAILHOG_ENABLED=true
NHOST_DASHBOARD_ENABLED=true

# Development domains
DOMAIN=local.nself.org
SSL_MODE=none

Production Configuration

# .env.prod-template - Production template
# Copy to .env before deployment
PROJECT_NAME=my-app
ENV=prod  # New in v0.2.1
DEBUG=false
LOG_LEVEL=warn

# Database with strong password
POSTGRES_PASSWORD=very-secure-production-password
POSTGRES_DB=myapp

# Security
HASURA_GRAPHQL_ADMIN_SECRET=very-secure-admin-secret
HASURA_GRAPHQL_JWT_SECRET={"type":"HS256","key":"very-long-jwt-secret-key"}

# SSL
DOMAIN=api.myapp.com
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@myapp.com

# Performance
POSTGRES_MEMORY_LIMIT=2048MB
HASURA_MEMORY_LIMIT=1024MB
REDIS_MEMORY_LIMIT=512MB

# Disable development services
MAILHOG_ENABLED=false
NHOST_DASHBOARD_ENABLED=false

Copy .env.prod-template to .env before deployment.

Next Steps

Now that you understand environment variables:

Environment variables provide flexible configuration for all aspects of your nself deployment. Use them to customize your setup without modifying code.