Configuration

nself provides flexible configuration through environment variables and configuration files. This guide covers all configuration options for customizing your backend infrastructure.

Configuration Files

When you run nself init, several configuration files are created:

my-project/
├── .env.local          # Main configuration file
├── .env.example        # Template with all options
├── .env.prod-template     # Production template (copy to .env before deployment)
└── docker-compose.yml  # Generated from config (do not edit)

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

Core Configuration

Project Settings

# Basic project configuration
PROJECT_NAME=my-backend
ENV=dev  # v0.2.1+ simplified: 'dev' or 'prod'
# ENVIRONMENT=development  # Legacy (still supported)

# Domain configuration
DOMAIN=localhost
SUBDOMAIN_PREFIX=
SSL_MODE=none

Database Configuration

# PostgreSQL settings
POSTGRES_DB=myapp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secure_password_here
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# Database management
DB_AUTO_MIGRATE=false
DB_SEED_ON_INIT=true
DB_ENV_SEEDS=true  # v0.2.1+ use environment-specific seed directories
DB_BACKUP_RETENTION=7

Redis Configuration

# Redis cache and sessions
REDIS_ENABLED=true
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

Service Configuration

Core Services

# Hasura GraphQL Engine
HASURA_GRAPHQL_ENABLED=true
HASURA_GRAPHQL_ADMIN_SECRET=myadminsecretkey
HASURA_GRAPHQL_JWT_SECRET={"type":"HS256","key":"myverylongjwtsecret"}

# MinIO Storage
MINIO_ENABLED=true
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_DEFAULT_BUCKETS=uploads,avatars,documents

# Email (MailHog for development)
MAILHOG_ENABLED=true
SMTP_HOST=mailhog
SMTP_PORT=1025

Optional Services

# Nhost Dashboard
NHOST_DASHBOARD_ENABLED=true
NHOST_DASHBOARD_PORT=3030

# Functions
FUNCTIONS_ENABLED=false
FUNCTIONS_RUNTIME=node

# Nginx Proxy
NGINX_ENABLED=true
NGINX_CLIENT_MAX_BODY_SIZE=100M

Microservices Configuration

NestJS Services

# Enable NestJS microservices
NESTJS_SERVICES=api,webhooks,auth-service

# NestJS specific settings
NESTJS_VERSION=10.x
NESTJS_SWAGGER=true
NESTJS_CORS_ENABLED=true
NESTJS_RATE_LIMIT=100

# Service scaling
NESTJS_API_REPLICAS=2
NESTJS_WEBHOOKS_REPLICAS=1

BullMQ Workers

# Background job processing
BULLMQ_WORKERS=email-worker,image-processor

# Worker configuration
BULLMQ_EMAIL_CONCURRENCY=5
BULLMQ_IMAGE_CONCURRENCY=3
BULLMQ_DASHBOARD_ENABLED=true
BULLMQ_DASHBOARD_PORT=3001

Python Services

# FastAPI microservices
PYTHON_SERVICES=ml-api,data-processor

# Python configuration
PYTHON_VERSION=3.11
PYTHON_ASYNC=true
PYTHON_CORS=true
PYTHON_DOCS=true

Go Services

# Go microservices
GOLANG_SERVICES=api-gateway,websocket-server

# Go build settings
GOLANG_VERSION=1.21
GOLANG_CGO_ENABLED=0
GOLANG_BUILD_TAGS=netgo

Environment-Specific Configuration

Development Settings

# Development environment (.env.local)
ENV=dev  # v0.2.1+ simplified
DEBUG=true
LOG_LEVEL=debug

# Development-only services
MAILHOG_ENABLED=true
NHOST_DASHBOARD_ENABLED=true
SWAGGER_ENABLED=true

# Hot reloading
AUTO_RELOAD=true
WATCH_FILES=true

Production Settings

# Production environment (.env.prod-template)
# Copy to .env before deployment
ENV=prod  # v0.2.1+ simplified
DEBUG=false
LOG_LEVEL=info

# Security
SSL_MODE=letsencrypt
FORCE_SSL=true
SECURE_COOKIES=true

# Performance
WORKER_PROCESSES=4
CACHE_TTL=3600
GZIP_ENABLED=true

# Monitoring
HEALTH_CHECK_ENABLED=true
METRICS_ENABLED=true

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

Security Configuration

Authentication & Authorization

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-here
JWT_EXPIRES_IN=7d
JWT_ALGORITHM=HS256

# Session settings
SESSION_SECRET=your-session-secret-here
SESSION_TIMEOUT=24h
COOKIE_SECURE=true
COOKIE_HTTP_ONLY=true

CORS & Security Headers

# CORS configuration
CORS_ORIGIN=http://localhost:3000,https://myapp.com
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_CREDENTIALS=true

# Security headers
CSP_ENABLED=true
HSTS_ENABLED=true
X_FRAME_OPTIONS=DENY

Networking Configuration

Port Configuration

# Service ports
HASURA_PORT=8080
POSTGRES_PORT=5432
REDIS_PORT=6379
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
MAILHOG_PORT=8025
NHOST_DASHBOARD_PORT=3030

# Custom service ports
NESTJS_API_PORT=3000
PYTHON_ML_API_PORT=8001
GOLANG_GATEWAY_PORT=8002

SSL/TLS Configuration

# SSL settings
SSL_MODE=custom
SSL_CERT_PATH=/etc/ssl/certs/server.crt
SSL_KEY_PATH=/etc/ssl/private/server.key
SSL_CA_PATH=/etc/ssl/certs/ca.crt

# Let's Encrypt
LETSENCRYPT_EMAIL=admin@myapp.com
LETSENCRYPT_DOMAINS=myapp.com,api.myapp.com

Performance Configuration

Resource Limits

# Memory limits (in MB)
POSTGRES_MEMORY_LIMIT=1024
REDIS_MEMORY_LIMIT=256
HASURA_MEMORY_LIMIT=512
NESTJS_MEMORY_LIMIT=256

# CPU limits
POSTGRES_CPU_LIMIT=1.0
HASURA_CPU_LIMIT=0.5
NESTJS_CPU_LIMIT=0.3

Caching Configuration

# Application caching
CACHE_ENABLED=true
CACHE_TTL=3600
CACHE_MAX_SIZE=100MB

# Database query caching
QUERY_CACHE_ENABLED=true
QUERY_CACHE_SIZE=50MB

# Static file caching
STATIC_CACHE_TTL=86400

Logging Configuration

Log Levels & Output

# Logging configuration
LOG_LEVEL=info
LOG_FORMAT=json
LOG_TIMESTAMP=true
LOG_COLORS=true

# Log destinations
LOG_TO_FILE=true
LOG_FILE_PATH=/var/log/nself/app.log
LOG_FILE_MAX_SIZE=100MB
LOG_FILE_MAX_FILES=5

# Service-specific logging
POSTGRES_LOG_LEVEL=warn
HASURA_LOG_LEVEL=info
REDIS_LOG_LEVEL=notice

Backup Configuration

Automated Backups

# Database backups
BACKUP_ENABLED=true
BACKUP_SCHEDULE=0 2 * * *  # Daily at 2 AM
BACKUP_RETENTION=7
BACKUP_COMPRESSION=true
BACKUP_LOCATION=./backups

# Storage backups
MINIO_BACKUP_ENABLED=true
MINIO_BACKUP_SCHEDULE=0 3 * * *

Configuration Management

Environment Variables

# Check current configuration
nself config show

# Validate configuration
nself config validate

# Set configuration value
nself config set POSTGRES_PASSWORD new_password

# Generate production config
nself config generate --env production

Configuration Templates

# Use predefined templates
nself init --template blog        # Blog/CMS setup
nself init --template ecommerce   # E-commerce setup
nself init --template api         # API-only setup
nself init --template minimal     # Minimal setup

Advanced Configuration

Custom Docker Configuration

# Docker settings
DOCKER_REGISTRY=docker.io
DOCKER_NAMESPACE=myorg
DOCKER_TAG=latest

# Build settings
DOCKER_BUILDKIT=1
DOCKER_MULTI_PLATFORM=true
DOCKER_CACHE_FROM=myorg/cache:latest

Health Checks

# Health check configuration
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_INTERVAL=30s
HEALTH_CHECK_TIMEOUT=5s
HEALTH_CHECK_RETRIES=3

# Service-specific health checks
POSTGRES_HEALTH_CHECK=SELECT 1
REDIS_HEALTH_CHECK=PING
HASURA_HEALTH_CHECK=/healthz

Configuration Best Practices

Security

Never commit secrets: Use .env.local and add it to .gitignore
Use strong passwords: Generate secure passwords for all services
Rotate secrets regularly: Update passwords and keys periodically
Environment separation: Use different secrets for each environment

Organization

Group related settings: Keep related configuration together
Use consistent naming: Follow naming conventions for variables
Document custom settings: Add comments for non-obvious configuration
Version control templates: Keep .env.example in version control

Troubleshooting Configuration

Common Issues

# Check configuration syntax
nself config validate

# View resolved configuration
nself config show --resolved

# Test database connection
nself db ping

# Verify service connectivity
nself status --verbose

Debug Mode

# Enable debug mode
DEBUG=true nself up

# View configuration with debug info
nself config show --debug

# Check environment variables
nself config env

Next Steps

Now that you understand configuration:

Environment Variables - Detailed environment variable reference
Production Deployment - Production configuration best practices
SSL/TLS Configuration - Secure your deployment
Monitoring & Logs - Configure monitoring and logging

Proper configuration is essential for a successful nself deployment. Take time to understand and customize these settings for your specific needs.