Quick Start Guide

Updated for ɳSelf v0.4.8 v0.4.8

Prerequisites

Before you begin, make sure you have:

• A Linux, macOS, or Windows (with WSL) system
• An internet connection for downloading dependencies

That's it! ɳSelf will automatically install Docker, Docker Compose, and any other required dependencies.

Step 1: Install ɳSelf

Run this single command to install the ɳSelf CLI:

curl -sSL https://install.nself.org | bash

The installer will:

• Download the latest ɳSelf CLI
• Install it to ~/.ɳSelf/bin
• Add ɳSelf to your PATH
• Verify the installation

Step 2: Create Your Project

Create a new directory for your project and initialize ɳSelf:

mkdir my-backend && cd my-backend
nself init

You'll be asked a few questions (or accept defaults):

• Project name
• Domain (default: local.nself.org)
• Which services to enable

What gets created:

my-backend/
├── .env           # Your configuration
├── .env.secrets   # Sensitive credentials (auto-generated)
└── ɳSelf/         # Project directory

Step 3: Build and Start

nself build    # Generate docker-compose.yml, nginx configs, etc.
nself start    # Launch all services

First start takes 2-5 minutes (downloading Docker images).

Check status:

nself status   # Service health
nself urls     # Access URLs

Step 4: Design Your Database (Recommended)

ɳSelf uses a database-first approach. Design your schema, and everything else follows.

Option A: Use a Template

nself db schema scaffold basic    # Creates schema.dbml

Available templates: basic, ecommerce, saas, blog

Option B: Design Visually

1. Go to dbdiagram.io
2. Design your schema
3. Export as DBML
4. Save as schema.dbml in your project

Apply Your Schema

nself db schema apply schema.dbml

This single command creates SQL migration, runs it, generates mock data, and seeds sample users.

Step 5: Explore Your Backend

Trust SSL Certificates

For HTTPS to work without browser warnings:

ɳSelf trust

Access Points

Try These Commands

# Check all URLs
nself urls

# View logs
nself logs

# Database shell
nself db shell

# Run a query
nself db query "SELECT * FROM users"

# Generate TypeScript types
nself db types

Step 6: To Production (When Ready)

# Create production environment
nself env create prod production

# Edit server configuration
# .environments/prod/server.json

# Deploy
nself deploy prod

See Deployment Guide for complete instructions.

Enable More Services

Edit .env and add:

# Enable Redis
REDIS_ENABLED=true

# Enable MinIO (S3 storage)
MINIO_ENABLED=true

# Enable search
MEILISEARCH_ENABLED=true

# Enable monitoring (10 services)
MONITORING_ENABLED=true

# Enable admin dashboard
NSELF_ADMIN_ENABLED=true

Then rebuild:

nself build && nself restart

Install Plugins (v0.4.8)

Extend ɳSelf with third-party integrations:

# List available plugins
nself plugin list

# Install Stripe for payments
nself plugin install stripe

# Install GitHub for CI/CD integration
nself plugin install github

# Install Shopify for e-commerce
nself plugin install shopify

Plugins automatically create database tables, set up webhook handlers, and provide CLI commands for managing synced data.

Common Commands

Everyday Use

nself start              # Start services
nself stop               # Stop services
nself restart            # Restart services
nself status             # Check health
nself logs               # View all logs
nself logs postgres      # View specific service

Database

nself db migrate up      # Run migrations
nself db migrate create NAME  # Create migration
nself db seed            # Seed data
nself db backup          # Create backup
nself db restore         # Restore backup
nself db shell           # PostgreSQL shell
nself db types           # Generate types

Project Management

nself build              # Regenerate configs
nself urls               # Show all URLs
nself doctor             # Diagnose issues
nself reset              # Reset to clean state

Plugin Management (v0.4.8)

nself plugin list                 # Show available plugins
nself plugin install stripe       # Install a plugin
nself plugin status               # Check plugin health
nself plugin stripe sync          # Sync data from Stripe
nself plugin stripe customers list  # View synced customers

Troubleshooting

Services won't start

• Check Docker is running: docker ps
• View logs: nself logs
• Ensure ports aren't in use: netstat -tulpn | grep LISTEN

Database connection issues

• Verify PostgreSQL is running: docker ps | grep postgres
• Check credentials in .env.local
• Try resetting: nself reset (⚠️ deletes all data)

Can't access web interfaces

• Check firewall settings
• Ensure services are running: nself status
• Try accessing via localhost instead of 127.0.0.1

Getting Help

• Documentation: Full documentation
• GitHub Issues: Report bugs or request features
• Examples: Check the examples directory

Ready to dive deeper? Check out our Architecture Overview to understand how everything works together.