nself build

Generate docker-compose.yml, nginx reverse-proxy configs, and SSL certificates from your .env file. Run this every time you change .env before calling nself start.

Quick start

# Standard workflow: edit .env, build, start
nself build
nself start

# Preview what would be generated without writing files
nself build --dry-run

# Validate your .env before building
nself build --validate

Synopsis

nself build [FLAGS]

Description

nself build reads your project .env file (following the cascade.env.dev → .env.local → .env.staging/.env.prod → .env.secrets → .env.computed) and generates the complete infrastructure definition:

• docker-compose.yml — includes every enabled service: the four required (Postgres, Hasura, Auth, Nginx) plus any optional services (MinIO, Redis, Functions, Mail, Search) and your custom services (CS_1 through CS_10).
• nginx/sites/ — one .conf fragment per service, assembled into the main nginx config by the Nginx container at startup.
• ssl/ — self-signed certificates for local development or Let's Encrypt ACME challenge stubs for production.
• Monitoring configs — Prometheus scrape rules, Grafana dashboards, and Alertmanager routing when monitoring is enabled in .env.

The generated docker-compose.yml carries the header comment # GENERATED BY nself build — DO NOT HAND EDIT. This is intentional: the file is owned by the build step, not by you. All configuration belongs in .env.

Flags

Generated file structure

project/
├── docker-compose.yml          # GENERATED — main Docker Compose config
├── nginx/
│   ├── nginx.conf              # GENERATED — root nginx config (do not edit)
│   ├── sites/
│   │   ├── hasura.conf         # GENERATED — per-service fragments
│   │   ├── auth.conf
│   │   ├── storage.conf
│   │   └── ...
│   └── conf.d/                 # HAND-MANAGED — safe to edit, never overwritten
│       └── custom.conf
└── ssl/
    ├── cert.pem                # GENERATED — TLS certificate
    └── key.pem                 # GENERATED — TLS private key

Examples

Basic build and start

# The standard sequence after any .env change:
nself build
nself start

Validate before building

# Catch .env errors before generating files
nself build --validate

# Validate and preview (no disk writes)
nself build --validate --dry-run

Environment-specific build

# Build for staging (loads .env.staging)
nself build --env staging

# Build for production (loads .env.prod)
nself build --env prod

Clean rebuild

# Remove stale generated files, then rebuild from scratch
nself build --clean --force

Verbose output (useful for debugging)

nself build --verbose
# Generated: docker-compose.yml (12 services)
# Generated: nginx/nginx.conf
# Generated: nginx/sites/hasura.conf
# Generated: nginx/sites/auth.conf
# ...

When to run build

• After any change to .env, .env.dev, .env.staging, or .env.prod
• After installing or removing a plugin with nself plugin install/remove
• After enabling or disabling an optional service
• After adding a custom service (CS_N)
• Before deploying to a new environment

See also

• nself start — boot the stack after building
• nself clean — remove generated artifacts
• nself config — inspect and edit .env values
• nself init — initialize a new project with a .env scaffold