cmd start

nself start

Boot the ɳSelf stack with health checks and automatic database initialization.

Synopsis

nself start [flags]
nself up [flags]

Alias: up

Description

nself start brings up the entire ɳSelf stack in the correct order: PostgreSQL first, then automatic database initialization (schemas, extensions, permissions), then Hasura, Auth, Nginx, optional services, monitoring, and custom services. Each service is health-checked before the next group starts.

Before launching containers, nself start validates that docker-compose.yml exists (run nself build first), the Docker daemon is running, and all required ports are available. A pre-flight port check scans for conflicts on ports 80, 443, 5432, 8080, 4000, 6379, and 9000 and reports the conflicting process name if a port is in use.

Database initialization is automatic and idempotent, ɳSelf creates the database, schemas (auth, storage, public), and extensions (pgcrypto, citext, uuid-ossp) if they do not already exist. After all services are healthy, the console prints all service URLs.

Flags

Flag	Default	Description
--fresh	false	Force recreate all containers
--force-recreate	false	Alias for --fresh
--clean-start	false	Remove all containers before starting
--skip-build	false	Skip automatic rebuild detection
--skip-health-checks	false	Skip health validation after startup
--skip-port-check	false	Skip port availability check
--quick	false	Quick start (timeout=30s, required=60%)
--timeout	120	Health check timeout in seconds (range: 30–600)
--quiet	false	Suppress progress output (for CI). Preserves --json output.
--watch	false	Enable health auto-restart: poll services and restart unhealthy containers
--skip-plugins	false	Start base stack only, skipping plugin compose files
--no-monorepo	false	Disable automatic monorepo backend detection
--allow-legacy	false	Bypass v0.9 artifact check and proceed with WARNING (not recommended). Use only as a temporary workaround while running nself migrate.
--embedded-pg	false	Boot PostgreSQL via embedded pglite/wasmtime — no Docker postgres container required. pgvector is included. See Embedded-Postgres for details.
--skip-db-init	false	Skip database migrations and seed; bring up Postgres, Hasura, and hasura-auth only. Exits 0 when all three backend services are healthy. Intended for CI/E2E environments that manage schema state themselves. Equivalent to setting NSELF_SKIP_DB_INIT=true.
--debug, -d	false	Show debug information
--verbose, -v	false	Show detailed Docker output
--help, -h	—	Show help

v0.9 project detection

nself start scans the current directory for v0.9 project artifacts before launching any containers. Detection uses five heuristics (v0.9 docker-compose.yml header, NSELF_VERSION=0.x in .env, flat nginx/ layout, .nself/config as a plain file, and nself.sh bootstrap script). Two or more hits trigger a hard error:

error: v0.9 project detected. Found 3 legacy artifact(s): docker-compose.yml, .env, nginx/nginx.conf
Run `nself migrate` first. See https://docs.nself.org/migrate/from-v0.9

A single hit produces a non-blocking warning. Use nself migrate detect to see all detected artifacts before running the migration. See Upgrade-From-v0.9 for the full migration guide.

Examples

# Standard boot
nself start

# Using the alias
nself up

# Force container recreation (useful after config changes)
nself start --fresh

# Remove existing containers before starting fresh
nself start --clean-start

# Fast mode for CI — lower timeout, 60% health threshold
nself start --quick

# CI/E2E mode: skip migrations and seed; block until postgres+hasura+auth are healthy
nself start --skip-db-init

# CI/E2E mode via environment variable (no script changes needed)
NSELF_SKIP_DB_INIT=true nself start

# Skip health checks (not recommended for production)
nself start --skip-health-checks

# Custom health check timeout
nself start --timeout 300

# Verbose output to debug startup issues
nself start -v

# Suppress progress output for CI pipelines
nself start --quiet

# Boot without a Docker postgres container (embedded pglite/wasmtime)
nself start --embedded-pg

First-run transcript

On the very first nself start in a project directory, the CLI detects that Docker images have not been pulled yet and streams progress to avoid a silent terminal during the 1-3 minute pull:

[1/7] Checking docker-compose.yml ✓
[2/7] Loading configuration ✓
[3/7] Checking port availability ✓
[4/7] Starting PostgreSQL
First run detected — pulling Docker images (this takes 1-3 minutes on slow connections)...
⚙ Pulling images [12s elapsed] — first run takes 1-3 minutes...
⚙ Pulling images [16s elapsed] — first run takes 1-3 minutes...
⚙ Pulling images [24s elapsed] — first run takes 1-3 minutes...
✓ Docker images ready
...

The progress line updates every 4 seconds. Once all images are pulled, the marker file .nself/.first-run-complete is written and subsequent starts skip the pull step entirely.

Pass --quiet to suppress all progress output. Useful in CI where the log is captured elsewhere.

Aliases

nself up is a hidden alias for nself start. Same flags. Same behavior. Provided so docker-compose users can keep their muscle memory.

← Commands | Home →