cmd start

nself start

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

Synopsis

nself start [flags]

Alias: nself 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. The pre-flight port check reports the conflicting process name if a port is in use.

Which ports get checked

The check reads the ports your project actually publishes, from the resolved docker compose config. It does not test a fixed list of ɳSelf defaults.

That matters when you run more than one ɳSelf project on one host. The second project has to move off the defaults:

POSTGRES_PORT=5433
HASURA_PORT=8181
AUTH_PORT=4001
REDIS_PORT=6380

Those are the ports it binds, so those are the ports checked. The first project holding 5432 and 8080 is not a conflict for the second and no longer blocks it. Before v1.3.4 it did, which could leave a correctly configured stack unable to start over ports it never touches.

Conflicts name the service from your compose file, so a moved port reads Port 8181 (hasura) rather than unknown service.

If the compose config cannot be read, the check falls back to the default list (80, 443, 5432, 8080, 4000, 6379, 9000, 9001, 7700, 3021, 1025, 8025, 3008, 5000) and says so. It never skips the check silently.

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.

Since v1.2.2, when the project uses a default local domain (unset, localhost, or local.nself.org), the printed ready URLs are direct http://localhost:<port> endpoints (GraphQL, Hasura console, Auth, Storage, Mail UI, Admin) that work on a fresh machine with no DNS setup. The nginx-routed *.local.nself.org URLs are listed separately with a requires: nself dns-setup hint. Custom domains keep nginx-routed URLs unchanged. Start also removes stale rename-leftover containers (hex-prefixed names such as b6d7...78_myapp_hasura from an interrupted recreate) before and after compose up, so docker exec <project>_<service> names stay stable, and passes .nself/compose.env to docker compose via --env-file for secret interpolation (see cmd-build).

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://nself.org/docs/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.

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.

Flags

Flag	Default	Description
--allow-legacy	false	Bypass v0.9 artifact check and proceed with WARNING (not recommended)
--clean-start	false	Remove all containers before starting
--debug, -d	false	Show debug information
--embedded-pg	false	Boot PostgreSQL via embedded pglite/wasmtime — no Docker postgres container required; pgvector included
--force-recreate	false	Alias for --fresh
--fresh	false	Force recreate all containers
--profile	""	Service profile passed to an automatic rebuild when the compose file is stale. app (default) — full service set. ops — observability + CI server (postgres, hasura, auth, nginx, monitoring). Overrides NSELF_PROFILE env var. Has no effect when --skip-build is set.
--quick	false	Quick start (timeout=30, required=60%)
--quiet	false	Suppress progress output (for CI; preserves --json output)
--skip-build	false	Skip automatic rebuild detection
--skip-db-init	false	Skip database migrations and seed; bring up Postgres+Hasura+hasura-auth only. Intended for CI/E2E environments.
--skip-health-checks	false	Skip health validation after startup
--skip-plugins	false	Start base stack only, skip all plugin compose files
--skip-port-check	false	Skip port availability check
--timeout	120	Health check timeout in seconds (range: 30-600)
--verbose, -v	false	Show detailed Docker output
--watch	false	Enable health auto-restart: poll services and restart unhealthy containers
--help, -h	—	Show help

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

See Also

• Commands — full command index
• Core-Services — what a stack is made of

← Commands | Home →