Nhost self-hosted stack and more, in seconds!

Getting Started

Quick Start

Installation

Install the nself cli with a single command:

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

The installer automatically:

• Checks for Docker and Docker Compose
• Downloads nself to ~/.nself/bin
• Adds nself to your PATH
• Creates the global nself command

Deploy Your First Backend

# 1. Create a new project
mkdir my-backend && cd my-backend

# 2. Initialize with default configuration
nself init

# 3. Configure optional services in .env.local
# Enable: SERVICES_ENABLED=true
# Choose: NESTJS_ENABLED, BULLMQ_ENABLED, GOLANG_ENABLED, PYTHON_ENABLED

# 4. Build the project structure
nself build

# 5. Start all services (core + optional)
nself up

Your backend is now running at:

• GraphQL API: https://api.local.nself.org
• Auth Service: https://auth.local.nself.org
• Storage: https://storage.local.nself.org
• And more...

Key Features

Complete Backend Stack

Developer Experience

• Single Command: nself up starts everything (core + services)
• Environment Config: One .env.local file controls everything
• Production Ready: nself prod creates production overrides
• Quick Restart: nself restart for rapid iteration
• Unified Network: All services can communicate directly
• Hot Reload: Configuration changes apply automatically
• Frontend Proxying: Route your apps through Nginx with SSL

Production Ready

• SSL/TLS Included: Automatic HTTPS for all services
• Let's Encrypt: Free certificates for production
• Security Enforced: Production mode requires secure passwords
• Health Monitoring: Built-in health checks for all services
• Backup Support: Automated backups to S3

CLI Reference

Commands

Service Endpoints

All services are available at these URLs when using local.nself.org:

Configuration

Environment Variables

The .env.local file uses a 3NF (Third Normal Form) approach - define each value once:

# Core Settings
ENVIRONMENT=development
PROJECT_NAME=myapp
BASE_DOMAIN=local.nself.org

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secretpassword
POSTGRES_DB=nhost
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# Services
HASURA_GRAPHQL_ADMIN_SECRET=hasura-secret
STORAGE_ACCESS_KEY=minioaccesskey
STORAGE_SECRET_KEY=miniosecretkey

# Optional Services
ENABLE_REDIS=false
ENABLE_FUNCTIONS=false
ENABLE_MAILHOG=true

PostgreSQL Extensions

Enable extensions through environment variables:

# Time-series data
ENABLE_TIMESCALEDB=true

# Geospatial data
ENABLE_POSTGIS=true

# Vector embeddings
ENABLE_PGVECTOR=true

# Full-text search
ENABLE_PGFTS=true

Production Deployment

Using nself prod Command

The nself prod command simplifies production deployment:

# 1. Create production .env with secure auto-generated passwords
nself prod

# 2. Review generated files:
#    - .env.prod-template (production config with secure passwords)
#    - .env.prod-secrets (backup of generated passwords)

# 3. Edit .env.prod-template to set your domain and email

# 4. Copy to .env and deploy
cp .env.prod-template .env
nself up

The system prioritizes .env over .env.local when both exist:

• .env.local - Base configuration (development defaults)
• .env - Production overrides (only changed values)

Example production overrides:

# Production configuration
ENVIRONMENT=production
BASE_DOMAIN=api.mycompany.com
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@mycompany.com

# Strong passwords required
POSTGRES_PASSWORD=your-very-secure-password-here
HASURA_GRAPHQL_ADMIN_SECRET=another-very-secure-secret

Functions & Services

Nhost Functions (Serverless)

Deploy serverless functions alongside your backend:

# Enable serverless functions
FUNCTIONS_ENABLED=true

# Functions will be available at:
# https://functions.local.nself.org

NestJS Run Service

For constantly running microservices (similar to Nhost Run):

# Enable NestJS Run service
NESTJS_RUN_ENABLED=true

# Service will be available at:
# https://run.local.nself.org

The NestJS template includes:

• GraphQL resolver examples
• REST API endpoints
• Authentication integration
• Database access patterns
• WebSocket support
• Background job processing

Nhost Dashboard

Manage your backend with the official Nhost Dashboard:

# Enable Dashboard
DASHBOARD_ENABLED=true

# Dashboard will be available at:
# https://dashboard.local.nself.org

The dashboard provides:

• Database browser and editor
• GraphQL API explorer
• User management
• Storage file browser
• Logs and monitoring

Backend Services Framework

Enable additional backend services for complex applications. All services share the same Docker network as the core backend:

# Enable services directory
SERVICES_ENABLED=true

# NestJS Services (TypeScript/JavaScript)
NESTJS_ENABLED=true
NESTJS_USE_TYPESCRIPT=true
NESTJS_SERVICES=actions-api,webhook-handler
NESTJS_PORT_START=4000

# BullMQ Queue Workers (requires Redis)
BULLMQ_ENABLED=true
BULLMQ_WORKERS=email-worker,notification-worker
BULLMQ_DASHBOARD_PORT=3200

# GoLang Services
GOLANG_ENABLED=true
GOLANG_SERVICES=currency-fetcher,account-monitor
GOLANG_PORT_START=5000

# Python/FastAPI Services
PYTHON_ENABLED=true
PYTHON_SERVICES=data-analyzer,ml-predictor
PYTHON_PORT_START=6000

This creates a structured /services directory with:

• NestJS: Perfect for Hasura actions and webhooks
• BullMQ: Queue workers for background jobs (requires Redis)
• GoLang: High-performance microservices
• Python: ML/AI and data processing services

Key Features:

• Unified Networking: All services share the same network (can communicate via service names)
• Single Command: nself up starts everything (core + services)
• Health Checks: Built-in health monitoring for all services
• Shared Environment: Common configuration across all services
• Auto Port Assignment: Services get sequential ports automatically

Example inter-service communication:

// From NestJS service
const hasuraUrl = 'http://hasura:8080/v1/graphql';  // Direct access
const redisHost = 'redis';  // Direct access
const postgresUrl = process.env.DATABASE_URL;  // Shared database

Hello World Example

The hello world example demonstrates all services working together as "database fillers":

# Enable all services and Redis
SERVICES_ENABLED=true
REDIS_ENABLED=true
NESTJS_ENABLED=true
NESTJS_SERVICES=weather-actions
BULLMQ_ENABLED=true
BULLMQ_WORKERS=weather-processor,currency-processor
GOLANG_ENABLED=true
GOLANG_SERVICES=currency-fetcher
PYTHON_ENABLED=true
PYTHON_SERVICES=data-analyzer

Data Flow Architecture:

1. NestJS Weather Actions - Exposes Hasura actions for weather data
2. BullMQ Workers - Process weather/currency data in background queues
3. GoLang Currency Fetcher - High-performance currency rate fetching
4. Python Data Analyzer - ML predictions on collected time-series data

Database Schema (Time-Series Ready):

• Weather readings with location and timestamps
• Currency exchange rates with historical tracking
• Predictions and analysis results
• All tables use TimescaleDB hypertables for optimal performance

Example Hasura Query:

query GetWeatherAnalysis {
  weather_data(order_by: {timestamp: desc}, limit: 100) {
    location
    temperature
    humidity
    timestamp
    predictions {
      forecast_temperature
      confidence
    }
  }
}

Frontend Integration

Proxy your frontend applications through Nginx for unified routing:

# In .env.local
APP_ROUTE_1=3000:app.local.nself.org
APP_ROUTE_2=3001:admin.local.nself.org
APP_ROUTE_3=8080:dashboard.local.nself.org

Benefits:

• Automatic SSL for all apps
• WebSocket support
• Unified domain structure
• Built-in CORS handling
• No port management

Deployment Options

Vercel Integration

Deploy your frontend to Vercel while keeping your backend self-hosted:

1. Set production domain in .env.local
2. Configure Vercel environment variables
3. Point API calls to your backend domain

Example Vercel configuration:

{
  "env": {
    "NEXT_PUBLIC_GRAPHQL_URL": "https://api.yourdomain.com/v1/graphql",
    "NEXT_PUBLIC_AUTH_URL": "https://auth.yourdomain.com"
  }
}

Docker Swarm & Kubernetes

The generated docker-compose.yml is compatible with:

• Docker Swarm mode for multi-node deployments
• Kompose for Kubernetes conversion
• Portainer for visual management

About

The nself cli

Created by Aric Camarata, the nself cli makes it easy to deploy the complete Nhost.io stack on your own infrastructure. Whether you're building a new SaaS, mobile app, or internal tool, nself gives you enterprise-grade backend infrastructure with a single command.

Credits

The nself cli is powered by:

• Nhost.io - The open-source Firebase alternative
• Hasura - Instant GraphQL APIs
• PostgreSQL - The world's most advanced database
• MinIO - High-performance object storage

Contributing

The project is open source and welcomes contributions:

• GitHub: github.com/acamarata/nself
• Issues: Report bugs or request features
• Discussions: Join the community