Local Development

Full production stack on your laptop. Trusted HTTPS, hot reload, and environment switching in one command.

# 1. Install nself (macOS/Linux)
curl -fsSL https://install.nself.org | sh

# 2. Create a project
nself init my-app
cd my-app

# 3. Set up trusted HTTPS for dev
nself trust

# 4. Start the full stack
nself start

# Your stack is live:
#   API:     https://api.local.nself.org
#   Auth:    https://auth.local.nself.org
#   Storage: https://storage.local.nself.org
#   Admin:   https://admin.local.nself.org

Prerequisites

• macOS 12+, Ubuntu 22.04+, or Debian 12+
• Docker Desktop 4.x (macOS) or Docker Engine 24+ (Linux)
• 4 GB RAM available for Docker
• nself CLI — curl -fsSL https://install.nself.org | sh

Initial Setup

Initialize a project

# Interactive setup wizard
nself init

# Non-interactive (skip wizard)
nself init my-app --template default

# With a specific plugin bundle pre-configured
nself init my-chat-app --bundle nchat

# Output:
#   Creating project my-app...
#   Generating JWT keys...
#   Creating .environments/dev/.env...
#   Downloading base images...
#   Ready. Run: nself start

Trusted HTTPS

Local dev runs on *.local.nself.org with trusted certificates, matching production exactly:

# Install trusted local CA + wildcard cert
nself trust

# What it does:
#   • Installs mkcert
#   • Creates local CA (~/.local/share/mkcert/ on Linux)
#   • Trusts CA in macOS Keychain / Chrome / Firefox
#   • Issues *.local.nself.org wildcard cert

# Verify
nself trust status

Starting and Stopping

# Start all services
nself start

# Start with specific optional services
nself start --with mail --with search --with storage

# Start only required services (Postgres + Hasura + Auth + Nginx)
nself start --minimal

# Stop all services
nself stop

# Restart a single service (without stopping others)
nself service restart hasura

# View running services
nself status

Environment Management

Each environment has its own config directory under .environments/. Switch between dev, staging, and prod contexts without touching your running services.

.environments/
├── dev/
│   ├── .env          # shared dev config (committed)
│   └── .env.secrets  # dev secrets (gitignored)
├── staging/
│   ├── .env
│   └── .env.secrets
└── prod/
    ├── .env
    └── .env.secrets

# Switch active environment
nself env switch dev
nself env switch staging

# View current environment
nself env current

# List all environments
nself env list

# Set a variable in the current environment
nself env set MY_VAR my-value

# Set a secret (goes to .env.secrets, never committed)
nself env set --secret DATABASE_URL postgres://...

Logs and Debugging

# Follow all service logs
nself logs --follow

# Follow a specific service
nself logs hasura --follow

# Tail last 100 lines
nself logs --tail 100

# Filter by log level
nself logs --level error

# Open log viewer in browser (Grafana Loki, dev only)
nself logs --ui

Database Workflow

# Open Hasura console (browser)
nself db console

# Create a migration
nself db migration create add_user_preferences

# Apply pending migrations
nself db migrate

# Roll back last migration
nself db migrate rollback

# Reset database (dev only — drops everything and re-applies all migrations)
nself db reset

# Seed test data
nself db seed apply --file seeds/dev.sql

# Connect directly to Postgres
nself db shell

Plugin Development

# Install a plugin (free tier)
nself plugin install search

# Install a pro plugin (requires license key)
nself license set nself_pro_xxx...
nself plugin install ai

# List installed plugins
nself plugin list

# View plugin logs
nself logs ai --follow

# Uninstall
nself plugin uninstall ai

Hot Reload

Database schema changes apply without restarting the stack:

# Hasura watches for migration file changes and reloads automatically.
# To force a metadata reload:
nself db hasura reload

# Config changes require a service restart:
nself service restart hasura

# .env changes require a rebuild:
nself build && nself start

Admin UI

The ɳSelf Admin UI runs locally at https://admin.local.nself.org (disabled in production for security):

# Start the admin UI
nself admin start

# Open in browser
nself admin open

# The admin UI lets you:
#   • Manage services (start/stop/restart)
#   • View and apply migrations
#   • Monitor service health
#   • Manage plugins
#   • Switch environments
#   • View logs

Switching Between Projects

# Stop current project
nself stop

# cd to another project
cd ~/projects/other-app

# Start it (each project gets isolated services)
nself start

# Or run multiple projects on different port sets
nself start --port-offset 100   # starts on api.local.nself.org:443+100

Troubleshooting Dev Setup

# Diagnose any issue
nself doctor

# Port conflict
nself doctor --fix ports

# Certificate not trusted
nself trust remove && nself trust

# Services not starting
nself logs --since 10m
nself health --verbose

# Reset everything (nuclear option)
nself stop && nself db reset && nself start

Related

• SSL/TLS
• Domain configuration
• Production deployment
• Troubleshooting