README

ɳSelf Documentation

The Complete Self-Hosted Backend Platform

Deploy a complete backend in minutes, not days with ɳSelf.

---

🔄 v0.9.8 Command Update: Commands have been consolidated into a v1.0 structure. Old commands like nself billing, nself org, nself staging still work but are now organized under logical groupings: nself tenant billing, nself tenant org, nself deploy staging. See Command Consolidation Map for the complete reference.

---

Quick Navigation

I want to...	Go to...
Get started in 5 minutes	Quick Start Guide
Install nself	Installation
Understand core concepts	Architecture
Look up a command	Commands Landing
Configure my setup	Configuration Guide
Deploy to production	Deployment Guide
Fix a problem	Troubleshooting
See examples	Examples
Learn specific features	Tutorials

---

5-Minute Quick Start

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

# 2. Create your project
mkdir myapp && cd myapp
nself init

# 3. Build and start
nself build && nself start

# 4. Design your database (optional but recommended)
nself db schema scaffold basic    # Creates schema.dbml
nself db schema apply schema.dbml # Import → migrate → seed

Done! You now have:

• GraphQL API at api.local.nself.org
• Authentication at auth.local.nself.org
• Database with your schema
• Sample users to test with

View Full Quick Start Guide

---

What is ɳSelf?

ɳSelf is a complete self-hosted Backend-as-a-Service platform that provides all the features of commercial services like Supabase, Nhost, or Firebase, but runs entirely on your own infrastructure.

┌─────────────────────────────────────────────────────────────────────┐
│                          YOUR APPLICATION                            │
├─────────────────────────────────────────────────────────────────────┤
│   Frontend (React, Vue, Next.js, etc.)                              │
│   ↓ GraphQL queries and mutations                                   │
├─────────────────────────────────────────────────────────────────────┤
│                              ɳSelf                                   │
│                                                                      │
│   ┌──────────────────────────────────────────────────────────┐      │
│   │              ALWAYS RUNNING (4 services)                  │      │
│   │   PostgreSQL  ·  Hasura GraphQL  ·  Auth  ·  Nginx       │      │
│   └──────────────────────────────────────────────────────────┘      │
│                                                                      │
│   ┌──────────────────────────────────────────────────────────┐      │
│   │              OPTIONAL (enable as needed)                  │      │
│   │   Redis  ·  MinIO  ·  Search  ·  Mail  ·  Functions      │      │
│   │   MLflow  ·  Admin Dashboard                              │      │
│   └──────────────────────────────────────────────────────────┘      │
│                                                                      │
│   ┌──────────────────────────────────────────────────────────┐      │
│   │              MONITORING (all-or-nothing bundle)           │      │
│   │   Prometheus · Grafana · Loki · Tempo · Alertmanager     │      │
│   └──────────────────────────────────────────────────────────┘      │
│                                                                      │
│   ┌──────────────────────────────────────────────────────────┐      │
│   │              YOUR CUSTOM SERVICES                         │      │
│   │   Express · FastAPI · gRPC · BullMQ · and 40+ more       │      │
│   └──────────────────────────────────────────────────────────┘      │
│                                                                      │
│   ┌──────────────────────────────────────────────────────────┐      │
│   │              PLUGINS (v0.4.8)                             │      │
│   │   Stripe · GitHub · Shopify · and more                    │      │
│   └──────────────────────────────────────────────────────────┘      │
├─────────────────────────────────────────────────────────────────────┤
│   Runs on: Docker Compose · Any Cloud · Any Server · Laptop         │
└─────────────────────────────────────────────────────────────────────┘

Learn More About Architecture

---

Documentation Structure

Getting Started

Start here if you're new to ɳSelf

• Getting Started Guide - Complete getting started guide
• Quick Start - Get running in 5 minutes
• Installation - Detailed installation guide
• FAQ - Frequently asked questions
• Database Workflow - DBML to production in one command
• Demo Setup - Full demo with 25 services

Core Concepts

Understand how ɳSelf works

• Architecture - System design and components
• Project Structure - File organization
• Build System - How build works
• Services Overview - All available services

CLI Reference

Complete command documentation

• All Commands - Top-level command landing and index
• Core Commands - init, build, start, stop, status
• Database Commands - migrate, seed, mock, backup, schema, types
• Deployment Commands - SSH deployment, environments
• Performance Commands - Profiling and benchmarking
• Plugin Commands - Plugin management
• Quick Reference - Printable cheat sheet

Configuration

Configure your ɳSelf setup

• Configuration Guide - Complete configuration overview
• Environment Variables - All .env variables
• Start Command Options - Startup configuration
• Custom Services - CS_N variables
• Admin UI - Web dashboard setup

Deployment

Deploy to production

• Deployment Guide - Production deployment overview
• SSH Deployment - Zero-downtime deployment
• Environment Management - local, staging, production
• Security Guide - Production security
• Backup & Recovery - Database backups

Guides & Tutorials

Learn specific features and workflows

• Database Workflow - Design-first development
• Multi-App Setup - Multiple apps in one stack
• Service Communication - Microservices patterns
• OAuth Setup - Social login configuration
• Real-Time Features - Subscriptions and live data
• Organization Management - Multi-tenancy
• Billing & Usage - Usage tracking and billing
• All Tutorials - Step-by-step tutorials

Services

Available services and configuration

• Services Overview - All available services
• Required Services - Core 4: PostgreSQL, Hasura, Auth, Nginx
• Optional Services - 7 additional services
• Monitoring Bundle - 10-service observability stack
• Custom Services - Build from 40+ templates
• Service Templates - Template reference

Plugins (v0.4.8)

Extend ɳSelf with third-party integrations

• Plugin Overview - Plugin system introduction
• Plugin Development - Creating custom plugins
• Stripe Plugin - Payment processing
• GitHub Plugin - Repository sync
• Shopify Plugin - E-commerce integration

API Reference

GraphQL and REST APIs

• API Overview - API documentation
• GraphQL API - Hasura GraphQL reference
• Billing API - Billing endpoints
• White-Label API - White-label endpoints

Troubleshooting

Fix common issues

• Troubleshooting Guide - Common issues and solutions
• Doctor Command - Automated diagnostics
• Billing Troubleshooting - Billing issues
• White-Label Troubleshooting - Branding issues

Examples

Real-world examples and code

• Examples Index - All examples
• Features Overview - Feature examples
• Deployment Examples - Production setups
• Real-Time Chat - Real-time example

---

What's New

v0.9.8 - Security & CI/CD Complete (Current)

Latest Release: Complete security audit, CI/CD improvements, and documentation standardization.

See v0.9.8 Release Notes for details.

v0.9.7 - Command Consolidation (v1.0 Structure)

Major Update: Commands consolidated from 79 legacy top-level commands into 31 top-level commands for better organization:

• nself billing → nself tenant billing
• nself org → nself tenant org
• nself staging → nself deploy staging
• nself prod → nself deploy production
• nself storage → nself service storage
• nself oauth → nself auth oauth
• And 40+ more command mappings

View Complete Consolidation Map

v0.9.0 - Multi-Tenant Platform

Complete multi-tenancy with billing, white-labeling, and tenant isolation:

# Initialize multi-tenancy
nself tenant init

# Create tenant
nself tenant create "Acme Corp" --slug acme --plan pro

# Billing management (v0.9.6: consolidated from "nself billing")
nself tenant billing usage
nself tenant billing subscription upgrade pro

# Organization management (v0.9.6: consolidated from "nself org")
nself tenant org list

# Custom domains and SSL
nself tenant domains add app.example.com
nself tenant domains ssl app.example.com

# Brand customization
nself tenant branding set-colors --primary #0066cc

Note: All old commands still work with deprecation warnings. See Migration Guide.

OAuth Management

Comprehensive OAuth provider integration (v0.9.6: now under nself auth oauth):

# Enable multiple providers
nself auth oauth enable --providers google,github,slack,microsoft

# Configure credentials
nself auth oauth config google --client-id=xxx --client-secret=xxx

# Test configuration
nself auth oauth test google

v0.9.6: OAuth commands consolidated under nself auth oauth. Old syntax still works.

File Storage & Uploads

Advanced file storage with thumbnails, virus scanning, and compression:

# Upload with all features
nself service storage upload photo.jpg --all-features

# Generate GraphQL integration
nself service storage graphql-setup

# Manage uploads
nself service storage list users/123/

v0.9.6: Storage commands consolidated under nself service storage. Old syntax still works.

View v0.9.0 Release Notes

---

Key Features

Database-First Development

Design your schema visually, generate everything automatically.

nself db schema scaffold saas       # Start with a template
# Edit schema.dbml at dbdiagram.io
nself db schema apply schema.dbml   # Creates tables + mock data + users

Environment-Aware Safety

Different behavior for local, staging, and production.

Command	Local	Staging	Production
db mock	Works	Works	Blocked
db reset	Works	Confirm	Blocked
db seed users	Mock users	QA users	Only explicit users

Smart Defaults Everywhere

Zero configuration required for common cases.

nself db migrate up     # Just works - no flags needed
nself db backup         # Auto-names: myapp_local_20260122.sql
nself db seed           # Knows your environment
nself db types          # Generates TypeScript by default

40+ Service Templates

Build custom services in any language.

JavaScript/TypeScript: Express, Fastify, NestJS, Hono, BullMQ Python: FastAPI, Flask, Django, Celery Go: Gin, Fiber, Echo, gRPC Others: Rust, Java, PHP, Ruby, C#, Elixir

View All Templates

---

Minimal Path to Production

# 1. Local development (3 commands)
nself init && nself build && nself start

# 2. Design database
nself db schema scaffold saas
# Edit schema.dbml
nself db schema apply schema.dbml

# 3. To production (2 commands)
nself env create prod production
# Edit .environments/prod/server.json with your server
nself deploy prod

5-6 commands from blank folder to production.

View Complete Deployment Guide

---

Service Summary

Type	Count	Examples
Required	4	PostgreSQL, Hasura, Auth, Nginx
Optional	7	Redis, MinIO, Search, Mail, Functions, MLflow, Admin
Monitoring	10	Prometheus, Grafana, Loki, Tempo, Alertmanager, + exporters
Plugins	3+	Stripe, GitHub, Shopify, and more coming
Custom	Unlimited	Your services from 40+ templates

View Services Overview

---

Version History

Version	Date	Focus
v0.9.8	Jan 31, 2026	Security & CI/CD Complete (current)
v0.9.7	Jan 31, 2026	SQL Injection Fixes & Validation
v0.9.6	Jan 30, 2026	Command Consolidation
v0.9.5	Jan 30, 2026	Feature Parity & Security
v0.9.0	Jan 30, 2026	Multi-Tenant Platform
v0.4.8	Jan 24, 2026	Plugin System & Registry
v0.4.7	Jan 23, 2026	Infrastructure Everywhere
v0.4.6	Jan 22, 2026	Scaling & Performance
v0.4.5	Jan 21, 2026	Provider Support
v0.4.4	Jan 20, 2026	Database Tools

View Roadmap | View Changelog

---

Security

nself has been thoroughly audited for security vulnerabilities. The codebase is safe for production use.

Category	Status
Hardcoded Credentials	✅ PASS
API Keys & Tokens	✅ PASS
Command Injection	✅ PASS
SQL Injection	✅ PASS
Docker Security	✅ PASS
Git History	✅ PASS

View Complete Security Audit

---

Contributing

We welcome contributions! Whether it's bug reports, feature requests, documentation improvements, or code contributions.

• Contributing Guide - How to contribute
• Development Setup - Dev environment
• Cross-Platform Compatibility - Bash 3.2+ requirements
• CLI Output Library - Output formatting standards

---

Links

• GitHub: github.com/nself-org/cli
• Issues: Report bugs
• Discussions: Ask questions
• Plugin Registry: plugins.nself.org
• Commands: Top-level command index
• Roadmap: Future plans
• Changelog: Release changes
• License: Project license terms
• Root Policy: Root structure rules

---

Version 0.9.9 · January 31, 2026 · Commands · Changelog · License

ɳSelf - The complete self-hosted backend platform