Understanding the nself project structure helps you customize and extend your backend effectively. Each file and directory has a specific purpose in the orchestration of your services.
project-root/ # Your project directory
│
├── _backup/ # Auto-backups from nself operations
│ └── [timestamps]/ # Timestamped backup folders
│
├── auth/ # nHost Auth service configuration
│ └── config/ # Auth service config files
│
├── functions/ # Serverless functions directory
│ ├── dist/ # Compiled functions output
│ └── src/ # Function source code
│
├── hasura/ # Hasura GraphQL engine configuration
│ ├── metadata/ # Hasura metadata (tables, relationships)
│ └── migrations/ # Database migrations managed by Hasura
│
├── logs/ # Application and service logs
│
├── monitoring/ # Observability stack configuration
│ ├── grafana/ # Grafana dashboards and provisioning
│ ├── loki/ # Loki log aggregation config
│ ├── prometheus/ # Prometheus metrics collection config
│ ├── promtail/ # Promtail log shipper config
│ └── tempo/ # Tempo distributed tracing config
│
├── nginx/ # Nginx reverse proxy configuration
│ ├── conf.d/ # Individual service proxy configs
│ ├── ssl/ # SSL certificate symlinks
│ └── nginx.conf # Main Nginx configuration
│
├── postgres/ # PostgreSQL database configuration
│ └── init/ # Database initialization scripts
│ ├── 00-init.sql # Initial database and user setup
│ ├── 01-extensions.sql # Enable PostgreSQL extensions
│ ├── 02-schemas.sql # Create database schemas
│ ├── 10-hasura.sql # Hasura-specific setup
│ └── 20-auth.sql # Auth service database setup
│
├── services/ # Custom backend services
│ ├── bullmq_worker/ # BullMQ job queue worker service
│ ├── express_api/ # Express.js REST API service
│ ├── go_grpc/ # Go gRPC service
│ └── python_api/ # Python FastAPI service
│
├── ssl/ # SSL certificates storage
│ └── certificates/
│ ├── localhost/ # Local dev certificates
│ └── [domain]/ # Production domain certificates
│
├── storage/ # MinIO/S3 file storage
│ ├── temp/ # Temporary file uploads
│ └── uploads/ # Persistent file storage
│
├── .volumes/ # Docker volume mount points (hidden)
│ ├── postgres/ # PostgreSQL data persistence
│ ├── redis/ # Redis data persistence
│ └── minio/ # MinIO object storage data
│
├── docker-compose.yml # Main Docker Compose orchestration file
├── .env # Active environment configuration
├── .env.dev # Development environment settings
├── .env.staging # Staging environment settings
├── .env.prod # Production environment settings
├── .env.example # Example environment template
└── .gitignore # Git ignore rules_backup/ - Automatic backups created by nself during operations. Each timestamped folder contains previous versions of configuration files, useful for rollback scenarios.
.volumes/ - Docker volume mount points for persistent data storage. This hidden directory contains subdirectories for each stateful service (PostgreSQL, Redis, MinIO) ensuring data persists across container restarts.
auth/ - Configuration for the authentication service, including JWT settings, OAuth providers, email templates, and security rules.
hasura/ - GraphQL engine configuration containing:
functions/ - Serverless functions that extend your backend capabilities:
services/ - Your custom backend services generated from templates:
nginx/ - Reverse proxy configuration that routes all traffic:
ssl/certificates/ - SSL/TLS certificates for HTTPS:
postgres/init/ - Database initialization scripts executed in order:
storage/ - File storage managed by MinIO (S3-compatible):
monitoring/ - Complete observability stack configuration:
nself supports multiple environment configurations:
.env # Active configuration (symlink or copy)
.env.dev # Development settings (local development)
.env.staging # Staging settings (pre-production testing)
.env.prod # Production settings (live environment)
.env.example # Template with all available options.env.dev with debug enabled.env.staging with production-like settings.env.prod with security hardeningEach service runs in its own container with isolated:
Stateful data is stored in .volumes/ ensuring:
# Define in .env file using CS_N variables:
CS_1=my_service:express-js:8001
# Run build to generate from template
nself build
# Customize code in services/my_service/
# Rebuild with nself start.env, .volumes/, and ssl/certificates/_backup/ size and clean old backups periodically.env.test for testingA complete nself deployment includes 30+ integrated services: