Services Overview

nself provides a comprehensive set of backend services that work together to power modern web applications. This guide provides an overview of all available services, their purposes, and how they integrate with each other.

Service Categories

Core Services

These four services are always enabled and form the foundation of every nself deployment.

PostgreSQL

# PostgreSQL configuration
POSTGRES_VERSION=16-alpine
POSTGRES_DB=myapp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-password
POSTGRES_EXTENSIONS=uuid-ossp,pgcrypto,pg_trgm

# Access the database
nself db shell
nself db status

Hasura GraphQL Engine

# Hasura configuration
HASURA_VERSION=v2.44.0
HASURA_ROUTE=api
HASURA_GRAPHQL_ADMIN_SECRET=your-admin-secret
HASURA_GRAPHQL_ENABLE_CONSOLE=true    # Dev only
HASURA_GRAPHQL_DEV_MODE=true          # Dev only

# Access GraphQL endpoint
# https://api.local.nself.org/v1/graphql

Authentication Service

# Auth configuration
AUTH_VERSION=0.36.0
AUTH_ROUTE=auth
AUTH_JWT_SECRET=your-jwt-secret-minimum-32-characters
AUTH_ACCESS_TOKEN_EXPIRY=15m
AUTH_REFRESH_TOKEN_EXPIRY=7d

Nginx

# Nginx handles routing for all services:
# https://api.{BASE_DOMAIN}      -> Hasura (8080)
# https://auth.{BASE_DOMAIN}     -> Auth (4000)
# https://storage.{BASE_DOMAIN}  -> MinIO (9000)
# https://admin.{BASE_DOMAIN}    -> nself-admin (3021)
# etc.

Optional Services

Enable these services by setting their corresponding environment variables to true.

nself Admin UI

# Admin UI configuration
NSELF_ADMIN_ENABLED=true
NSELF_ADMIN_ROUTE=admin

# Features:
# - Service management
# - Log viewing
# - Configuration editor
# - SSL management
# - Project setup wizard

# Security: Disable in production!
# NSELF_ADMIN_ENABLED=false

MinIO (S3 Storage)

# MinIO configuration
MINIO_ENABLED=true
MINIO_ROUTE=storage
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin    # Change in production!

# Usage
aws s3 --endpoint-url https://storage.local.nself.org \
  cp file.txt s3://mybucket/file.txt

Redis

# Redis configuration
REDIS_ENABLED=true
REDIS_PORT=6379
REDIS_PASSWORD=        # Empty for dev, set for production
REDIS_MAXMEMORY=256MB
REDIS_MAXMEMORY_POLICY=allkeys-lru

# Access Redis CLI
nself exec redis redis-cli

MeiliSearch

# MeiliSearch configuration
MEILISEARCH_ENABLED=true
MEILISEARCH_ROUTE=search
MEILISEARCH_MASTER_KEY=your-master-key

# Alternative search engines
nself search enable postgres      # Built-in PostgreSQL FTS
nself search enable typesense     # Typesense
nself search enable elasticsearch # Elasticsearch

Serverless Functions

# Functions configuration
FUNCTIONS_ENABLED=true
FUNCTIONS_PORT=4300
FUNCTIONS_ROUTE=functions

# Create a function
nself functions create my-api --template api --ts

# Deploy functions
nself functions deploy local

MLflow

# MLflow configuration
MLFLOW_ENABLED=true
MLFLOW_ROUTE=mlflow

# MLflow commands
nself mlflow enable
nself mlflow experiments list
nself mlflow experiments create "My Experiment"

MailPit (Development)

# MailPit configuration (dev only)
MAILPIT_ENABLED=true
MAILPIT_ROUTE=mail

# SMTP configuration for auth service
AUTH_SMTP_HOST=mailpit
AUTH_SMTP_PORT=1025

# View captured emails at:
# https://mail.local.nself.org

Monitoring Bundle

When MONITORING_ENABLED=true, all 10 monitoring services are enabled together. Choose a profile based on your resource availability:

# Enable monitoring
MONITORING_ENABLED=true

# Choose profile
nself metrics enable minimal    # ~500MB RAM
nself metrics enable standard   # ~1GB RAM (default)
nself metrics enable full       # ~2GB RAM
nself metrics enable auto       # Auto-detect

Monitoring Services

# Access monitoring dashboards
nself monitor                   # Open Grafana
nself monitor grafana          # Open Grafana
nself monitor prometheus       # Open Prometheus
nself monitor alerts           # Open Alertmanager
nself monitor services         # CLI service status
nself monitor resources        # CLI resource usage

Custom Services (CS_N)

Define your own custom services using the CS_N pattern. nself supports multiple frameworks and templates.

Configuration Format

# Format: CS_N=name:framework[:port]
CS_1=api-gateway:express-ts:8001
CS_1_ROUTE=gateway
CS_1_PUBLIC=true

CS_2=worker:fastapi:8002
CS_2_REPLICAS=2
CS_2_PUBLIC=false

CS_3=ml-service:flask:8003
CS_3_MEMORY=1GB
CS_3_CPU=1.0

Available Frameworks

Custom Service Options

# Full configuration options for CS_1
CS_1=my-service:express-ts:8001
CS_1_ROUTE=api                  # Subdomain route
CS_1_PUBLIC=true                # Expose via nginx
CS_1_REPLICAS=2                 # Number of instances
CS_1_MEMORY=512M                # Memory limit
CS_1_CPU=1.0                    # CPU cores
CS_1_HEALTHCHECK=/health        # Health endpoint
CS_1_RATE_LIMIT=100             # Requests per minute
CS_1_ENV_VAR_1=KEY=value        # Additional env vars

Frontend Applications

Route external frontend applications through nginx using FRONTEND_APP_N variables.

# Frontend app routing
FRONTEND_APP_1_NAME=web
FRONTEND_APP_1_PORT=3000
FRONTEND_APP_1_ROUTE=web
# Accessible at https://web.{BASE_DOMAIN}

FRONTEND_APP_2_NAME=admin
FRONTEND_APP_2_PORT=3001
FRONTEND_APP_2_ROUTE=dashboard
# Accessible at https://dashboard.{BASE_DOMAIN}

FRONTEND_APP_3_NAME=docs
FRONTEND_APP_3_PORT=3002
FRONTEND_APP_3_ROUTE=docs
# Accessible at https://docs.{BASE_DOMAIN}

Service Management Commands

# View all services
nself status

# View service URLs
nself urls

# View logs for specific service
nself logs hasura
nself logs postgres
nself logs auth

# Restart specific service
nself restart hasura

# Execute command in service container
nself exec postgres psql -U postgres
nself exec redis redis-cli

# Check service health
nself health

Service Architecture

┌─────────────────────────────────────────────────────────────────┐
│                           Internet                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Nginx (SSL Termination)                     │
│         Ports: 80, 443    Routes: *.{BASE_DOMAIN}               │
└─────────────────────────────────────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
        ▼                       ▼                       ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│    Hasura     │    │     Auth      │    │    MinIO      │
│   (GraphQL)   │    │    Service    │    │  (Storage)    │
│   Port: 8080  │    │   Port: 4000  │    │  Port: 9000   │
└───────────────┘    └───────────────┘    └───────────────┘
        │                    │
        │                    │
        ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                        PostgreSQL                                │
│                        Port: 5432                                │
└─────────────────────────────────────────────────────────────────┘
        │
        ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│     Redis     │    │  MeiliSearch  │    │   Functions   │
│  Port: 6379   │    │  Port: 7700   │    │  Port: 4300   │
└───────────────┘    └───────────────┘    └───────────────┘

Service Dependencies

Next Steps

• Hasura - Deep dive into GraphQL configuration
• Authentication - Auth service configuration
• Storage - MinIO configuration and usage
• Search - Full-text search configuration
• Monitoring - Monitoring and observability
• Functions - Serverless functions guide

nself provides all the services you need for a modern backend. Start with the core services and enable optional services as your application grows.