Quick Start Guide

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! nself will automatically install Docker, Docker Compose, and any other required dependencies.

Step 1: Install nself

Run this single command to install the nself CLI:

curl -fsSL https://raw.githubusercontent.com/acamarata/nself/main/install.sh | bash

The installer will:

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

Step 2: Create Your Project

Create a new directory for your project and initialize nself:

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

This creates a .env.local file with default configuration values.

Step 3: Configure Your Backend

Open .env.local in your favorite editor and customize:

# Basic Configuration
PROJECT_NAME=my-backend
ENV=dev  # or 'prod' for production

# Database
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=myapp

# Optional Services (set to true to enable)
REDIS_ENABLED=true
FUNCTIONS_ENABLED=true
NHOST_DASHBOARD_ENABLED=true

# Database Seeding (v0.2.1+)
DB_ENV_SEEDS=true  # Use environment-specific seed directories

For development, the default values work great. For production, see our Production Deployment Guide.

Step 4: Build and Start

Generate your Docker configuration and start all services:

nself build
nself start  # or 'nself up' (both work the same)

Your backend is now running with 100% service reliability! 🎉

✨ New in v0.3.5: Enhanced with SSL Support

All 17 services now start successfully every time with smart port allocation (3000-3099 for frontends, 3100+ for system services) and complete HTTPS support.

Step 5: Enable SSL Trust (Recommended) v0.3.5

For the best development experience, enable SSL certificate trust to eliminate browser security warnings:

nself trust

This command installs trusted SSL certificates for both *.localhost and *.local.nself.org domains, giving you green lock security in all browsers.

Step 6: Access Your Services

After running nself trust, you can access your services with HTTPS (recommended):

đź”’ HTTPS (Recommended)

  • Hasura Console: https://hasura.localhost/console
  • Dashboard: https://dashboard.localhost
  • Storage Console: https://storage.localhost
  • MailPit: https://mailpit.localhost
  • Database Admin: https://adminer.localhost

HTTP (Legacy)

  • Hasura Console: http://localhost:8080/console
  • Dashboard: http://localhost:3030
  • MinIO Console: http://localhost:9001
  • MailPit: http://localhost:3101
  • PostgreSQL: localhost:5432

Dual Domain Support (v0.3.5)

nself now supports both *.localhost and *.local.nself.org domains with automatic SSL:

  • Localhost domains: Fastest access, Chrome/Safari optimized
  • Network domains: Accessible from other devices on your network
  • Green lock guarantee: All certificates trusted by browsers after nself trust

What's Next?

Explore the Database Tools

nself v0.2.2 includes powerful database management with environment-aware seeding:

# Check database status
nself db status

# Create and run migrations
nself db run

# Seed your database
nself db seed

# Create a backup
nself db backup

Add Microservices

Enable additional services in your .env.local:

# NestJS microservices
NESTJS_SERVICES=api,webhooks

# Python services
PYTHON_SERVICES=ml-processor

# Go services
GOLANG_SERVICES=data-fetcher

# BullMQ workers
BULLMQ_WORKERS=email-worker,notification-worker

Then rebuild and restart:

nself build && nself restart

Deploy to Production

When ready for production:

# Generate production configuration
nself prod

# Review and customize .env.prod-template
# Copy to .env before deployment
# Deploy to your server

Common Commands

# Service Management
nself up        # Start all services (100% reliability in v0.3.5)
nself down      # Stop all services
nself restart   # Restart all services
nself status    # Check service status
nself logs      # View logs

# SSL Management (v0.3.5)
nself trust           # Install SSL certificates and enable browser trust
nself trust status    # Check trust status
nself ssl bootstrap   # Bootstrap SSL certificates
nself ssl status      # Check SSL certificate status
nself ssl renew       # Renew SSL certificates

# Database Management
nself db run          # Generate migrations from schema.dbml
nself db update       # Apply migrations
nself db seed         # Seed database
nself db reset        # Reset database
nself db backup       # Create backup

# Configuration
nself build     # Rebuild configuration
nself reset     # Delete all data and reset
nself update    # Update nself CLI

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

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