Generate docker-compose.yml, nginx configs, and SSL certificates from .env.

nself build [flags]

nself build reads your .env cascade and generates all infrastructure configuration files: a docker-compose.yml with every enabled service, nginx reverse-proxy configs, and SSL certificates. It must be run after nself init and after any configuration change before restarting services.

The build pipeline loads configuration from .env.dev → .env.{ENV} → .env.secrets → .env.local → .env, merges plugin configurations from ~/.nself/plugins/, and applies security validation (password strength, no wildcard CORS in production, port binding checks). The result is a single docker-compose.yml that includes core services, optional services, monitoring, custom services (CS_1–CS_10), and any installed plugins.

By default, nself build is smart-cached: it compares .env modification time against docker-compose.yml and skips regeneration when nothing has changed. Use --force to override the cache.

nself build automatically includes a Redis service in docker-compose.yml when any installed plugin requires it, even if REDIS_ENABLED is not set in .env.

Plugins that trigger Redis auto-enable: ai, claw, mux, cron, notify.

When auto-enable fires, the build prints:

Note: Redis auto-enabled because a BullMQ-backed plugin (cron, notify, ai, claw, or mux) was detected.

To disable auto-enable, uninstall the plugin or explicitly set REDIS_ENABLED=false and confirm you do not need the plugin's queue features. To opt in explicitly and suppress the note, set REDIS_ENABLED=true in .env.

nself build scans for v0.9 project artifacts before generating any files. Two or more detected artifacts trigger a hard error pointing to the migration guide. A single artifact produces a non-blocking warning. Use --no-migration-check in automation (CI) where you are certain no v0.9 projects exist. Use --allow-legacy only as a temporary workaround while running nself migrate. See Upgrade-From-v0.9.

nself build generates compose files that are compatible with both Docker Compose v4 and v5.

Docker Compose v5 introduced a stricter parser: it treats the top-level pids_limit service field as a canonical alias for deploy.resources.limits.pids. When both are present, v5 rejects the compose file with:

services.<name>: can't set distinct values on 'pids_limit' and 'deploy.resources.limits.pids': invalid compose project

The generator uses the deploy.resources.limits.pids form exclusively. The pids_limit top-level field is never emitted. This form is also valid on Compose v3.4+ and v4, so generated files work across all current Docker Compose versions.

Each long-running service gets a default pids limit of 100 to prevent fork-bomb attacks. Services that need more (such as postgres under high concurrency) override this in their configuration.

# Standard build
nself build

# Validate config only, don't write files
nself build --check

# Force rebuild everything, ignoring cache
nself build --force

# CI mode — quiet output
nself build -q

# Show the environment cascade as it loads
nself build --verbose

# Generate a security analysis report
nself build --security-report

# Rebuild for a specific environment
nself build --force --verbose

← Commands | Home →