Deployment Architecture

This guide explains how nself deploys services across different environments and the distinction between staging and production deployments.

Service Categories

nself organizes services into five distinct categories:

1. Core Services (4) - Always Deployed

These are the foundational services required for any nself deployment:

Service	Purpose	Subdomain
PostgreSQL	Primary database	Internal only
Hasura	GraphQL API engine	`api.domain.com`
Auth	Authentication service (nhost-compatible)	`auth.domain.com`
Nginx	Reverse proxy & SSL termination	Main entry point

2. Optional Services (7) - Based on `*_ENABLED` Vars

Enable these based on your application needs:

Service	Enable Flag	Subdomain	Purpose
nself-admin	`NSELF_ADMIN_ENABLED=true`	`admin.domain.com`	Web management UI
MinIO	`MINIO_ENABLED=true`	`minio.domain.com`	S3-compatible storage
Redis	`REDIS_ENABLED=true`	Internal	Cache & sessions
Functions	`FUNCTIONS_ENABLED=true`	`functions.domain.com`	Serverless runtime
MLflow	`MLFLOW_ENABLED=true`	`mlflow.domain.com`	ML experiment tracking
Mailpit	`MAILPIT_ENABLED=true`	`mail.domain.com`	Dev email testing
Meilisearch	`MEILISEARCH_ENABLED=true`	`search.domain.com`	Full-text search

3. Monitoring Bundle (10) - All or Nothing

When MONITORING_ENABLED=true, all 10 services are deployed:

Service	Purpose
Prometheus	Metrics collection
Grafana	Dashboards & visualization
Loki	Log aggregation
Promtail	Log shipping (required for Loki)
Tempo	Distributed tracing
Alertmanager	Alert routing
cAdvisor	Container metrics
Node Exporter	System metrics
Postgres Exporter	Database metrics
Redis Exporter	Redis metrics

4. Custom Services (CS_N) - Your Backend Applications

Completely independent backend applications with custom business logic:

# In .env
CS_1=order-api:express-js:8001    # Order processing API
CS_2=webhooks:nestjs:8002         # Webhook handler service
CS_3=payments:fastapi-py:8003     # Payment processing
CS_4=ml-inference:fastapi-py:8004 # ML model serving

Custom services are separate applications that:

Have their own codebase and logic
May or may not connect to the database
Run as independent Docker containers
Can integrate with Hasura via Actions/Event Triggers

Examples:

Order processing API
Payment processing service
Email notification worker
ML inference endpoint
Third-party integration handlers (webhooks, callbacks)

5. Remote Schemas - Multi-App Hasura Endpoints

Different from Custom Services! Remote Schemas are multiple Hasura GraphQL endpoints for different apps/tenants, all accessing the same database with different exposed schemas:

Same nself instance, same PostgreSQL, different GraphQL APIs:

api.app1.com → Hasura endpoint exposing App1 tables/permissions
api.app2.com → Hasura endpoint exposing App2 tables/permissions

Use case: One nself deployment serving multiple applications:

www.app1.com uses api.app1.com (sees users, products, orders)
www.app2.com uses api.app2.com (sees different tables/fields)

Configuration in .env:

# Remote Schemas (multiple Hasura endpoints)
REMOTE_SCHEMA_1_NAME=app1
REMOTE_SCHEMA_1_DOMAIN=api.app1.com

REMOTE_SCHEMA_2_NAME=app2
REMOTE_SCHEMA_2_DOMAIN=api.app2.com

6. Frontend Apps (FRONTEND_APP_N) - External Applications

Frontend applications configured for Nginx routing:

# In .env
FRONTEND_APP_1_NAME=web
FRONTEND_APP_1_PORT=3000
FRONTEND_APP_1_ROUTE=app

FRONTEND_APP_2_NAME=admin
FRONTEND_APP_2_PORT=3001
FRONTEND_APP_2_ROUTE=dashboard

Key Point: These are NOT Docker containers - they run outside Docker and Nginx routes to them.

Deployment Flow

🔑 KEY DIFFERENCE: Frontend apps are included in staging (complete testing environment) but excluded in production (deployed separately to Vercel/CDN).

┌─────────────────────────────────────────────────────────────────┐
│                    LOCAL DEVELOPMENT                             │
│  nself init → nself build → nself start                         │
│  All services run in Docker on localhost                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       STAGING                                    │
│  nself deploy staging                                           │
│                                                                  │
│  ✅ Deploys: Core + Optional + Monitoring + Custom + Frontends │
│                                                                  │
│  Frontend apps served by Nginx on subdomains:                   │
│    app.staging.example.com → Frontend App 1                     │
│    dashboard.staging.example.com → Frontend App 2               │
│                                                                  │
│  Complete replica for testing everything together               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      PRODUCTION                                  │
│  nself deploy production                                        │
│                                                                  │
│  ✅ Deploys: Core + Optional + Monitoring + Custom              │
│  ❌ Frontend apps EXCLUDED by default (deploy separately)       │
│                                                                  │
│  Frontend apps deployed to specialized platforms:               │
│    ├── Vercel (Next.js, React) - Auto-scaling, edge cache      │
│    ├── Cloudflare Pages (static) - Global CDN                  │
│    ├── Mobile apps (App Store, Play Store)                      │
│    └── Any CDN/hosting platform                                 │
│                                                                  │
│  API endpoints exposed:                                          │
│    api.example.com → Hasura GraphQL                             │
│    auth.example.com → Authentication                            │
│                                                                  │
│  💡 Override: Use --include-frontends to deploy frontends       │
└─────────────────────────────────────────────────────────────────┘

Staging vs Production

⚠️ IMPORTANT: The key difference is frontend app deployment behavior!

Aspect	Staging	Production
Frontend Apps	✅ INCLUDED (Nginx serves)	❌ EXCLUDED (Vercel/CDN)
Hasura Console	✅ Enabled	❌ Disabled
Debug Mode	❌ Off	❌ Off
Log Level	`info`	`warning`
Mailpit	✅ Available	❌ Use real email
Monitoring	⚠️ Optional	✅ Required
Purpose	Testing & QA	Live users

Why This Distinction?

💡 TL;DR: Staging = test everything together. Production = backend on VPS, frontends on specialized platforms.

Staging: You want a complete replica to test everything together - frontend, backend, APIs, integrations. Nginx serves all frontend apps on staging subdomains. This ensures your staging environment matches the full user experience.

Production: Frontend apps have different scaling needs and are typically deployed on specialized platforms:

Vercel/Netlify: Automatic scaling, edge caching, preview deployments, serverless functions
Cloudflare Pages: Global CDN with 200+ edge locations, instant cache invalidation
Mobile Apps: App Store / Google Play (can't run on your VPS anyway)

Why separate?

✅ Better performance (global CDN vs single VPS)
✅ Lower costs (frontend hosting is often free)
✅ Easier deployment (Git push vs Docker rebuild)
✅ Better DX (preview deployments, instant rollbacks)

Your VPS focuses on what it does best: running the backend services, APIs, and databases.

Deployment Commands

Staging (Full Stack)

# Initialize staging
nself staging init staging.example.com --email [email protected]

# Configure server
# Edit .environments/staging/server.json

# Generate secrets
nself staging secrets generate

# Deploy everything
nself staging deploy

# What gets deployed:
#   ✓ Core Services (PostgreSQL, Hasura, Auth, Nginx)
#   ✓ Optional Services (based on *_ENABLED)
#   ✓ Monitoring Bundle (if enabled)
#   ✓ Custom Services (CS_1, CS_2, ...)
#   ✓ Frontend Apps (FRONTEND_APP_1, FRONTEND_APP_2, ...)

Production (Backend Only)

# Initialize production
nself prod init example.com --email [email protected]

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

# Generate secrets
nself prod secrets generate

# Security audit
nself prod check

# Deploy backend only
nself deploy prod

# What gets deployed:
#   ✓ Core Services (PostgreSQL, Hasura, Auth, Nginx)
#   ✓ Optional Services (based on *_ENABLED)
#   ✓ Monitoring Bundle (if enabled)
#   ✓ Custom Services (CS_1, CS_2, ...)
#   ○ Frontend Apps (excluded - deploy to Vercel/CDN)

Override Default Behavior

# Force include frontends in production (unusual)
nself deploy prod --include-frontends

# Exclude frontends in staging (e.g., testing backend only)
nself staging deploy --exclude-frontends

Hasura Integration

Remote Schemas (Multi-App Endpoints)

nself can serve multiple applications from one deployment using Remote Schemas - different Hasura GraphQL endpoints with different exposed schemas, all hitting the same database:

┌─────────────────────────────────────────────────────────────┐
│                    nself Deployment                          │
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ api.app1.com │    │ api.app2.com │    │  api.main    │  │
│  │  (Remote 1)  │    │  (Remote 2)  │    │  (Default)   │  │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘  │
│         │                   │                   │           │
│         └───────────────────┼───────────────────┘           │
│                             ▼                               │
│                    ┌─────────────────┐                      │
│                    │    PostgreSQL   │                      │
│                    │  (Same Database)│                      │
│                    └─────────────────┘                      │
└─────────────────────────────────────────────────────────────┘

Use case: SaaS platform serving multiple white-label apps from one backend.

Custom Services Integration

Custom Services (CS_N) are separate backend applications that can integrate with Hasura:

Hasura Actions

Your Custom Service handles business logic called from GraphQL:

# Custom service for complex operations
CS_1=order-service:nestjs:8001

In Hasura Console → Actions:

Handler URL: http://order-service:8001/validate-and-process
Expose as: processOrder mutation
Hasura handles auth, your service handles logic

Hasura Event Triggers

Your Custom Service reacts to database changes:

# Worker service for async processing
CS_2=notification-worker:express-js:8002

In Hasura Console → Events:

Webhook URL: http://notification-worker:8002/on-order-created
Trigger on: INSERT into orders table
Your service sends emails, updates analytics, etc.

Standalone APIs

Custom Services can also be completely independent:

# Telemetry API (no Hasura integration)
CS_3=telemetry:express-js:8003

# ML inference (no Hasura integration)
CS_4=ml-api:fastapi-py:8004

These run alongside nself but handle their own routing and logic.

Example Project Structure

my-project/
├── .environments/
│   ├── staging/
│   │   ├── .env              # Staging config
│   │   ├── .env.secrets      # Staging secrets
│   │   └── server.json       # Staging VPS SSH config
│   └── prod/
│       ├── .env              # Production config
│       ├── .env.secrets      # Production secrets
│       └── server.json       # Production VPS SSH config
├── .env.dev                   # Local development config
├── docker-compose.yml         # Generated by nself build
├── nginx/                     # Generated nginx configs
├── services/                  # Generated custom services
│   ├── payment_api/          # CS_1
│   ├── event_worker/         # CS_2
│   └── ml_inference/         # CS_3
└── frontend/                  # Your frontend apps (not in Docker)
    ├── web/                   # Next.js app → Vercel in prod
    └── mobile/                # React Native → App stores

Best Practices

Staging mirrors production config - Same services, same structure
Test everything in staging - Including frontend integrations
Production is backend-focused - Let specialized platforms handle frontends
Use Hasura for API - Custom services extend, don't replace it
Monitor everything - Enable monitoring bundle in staging and production
Secure secrets - Different secrets per environment, never commit them

DEPLOYMENT ARCHITECTURE - nself-org/cli GitHub Wiki

Deployment Architecture

Service Categories

1. Core Services (4) - Always Deployed

2. Optional Services (7) - Based on `*_ENABLED` Vars

3. Monitoring Bundle (10) - All or Nothing

4. Custom Services (CS_N) - Your Backend Applications

5. Remote Schemas - Multi-App Hasura Endpoints

6. Frontend Apps (FRONTEND_APP_N) - External Applications

Deployment Flow

Staging vs Production

Why This Distinction?

Deployment Commands

Staging (Full Stack)

Production (Backend Only)

Override Default Behavior

Hasura Integration

Remote Schemas (Multi-App Endpoints)

Custom Services Integration

Hasura Actions

Hasura Event Triggers

Standalone APIs

Example Project Structure

Best Practices

Related Documentation

⚠️ GitHub.com Fallback ⚠️

DEPLOYMENT ARCHITECTURE - nself-org/cli GitHub Wiki

Deployment Architecture

Service Categories

1. Core Services (4) - Always Deployed

2. Optional Services (7) - Based on *_ENABLED Vars

3. Monitoring Bundle (10) - All or Nothing

4. Custom Services (CS_N) - Your Backend Applications

5. Remote Schemas - Multi-App Hasura Endpoints

6. Frontend Apps (FRONTEND_APP_N) - External Applications

Deployment Flow

Staging vs Production

Why This Distinction?

Deployment Commands

Staging (Full Stack)

Production (Backend Only)

Override Default Behavior

Hasura Integration

Remote Schemas (Multi-App Endpoints)

Custom Services Integration

Hasura Actions

Hasura Event Triggers

Standalone APIs

Example Project Structure

Best Practices

Related Documentation

⚠️ **GitHub.com Fallback** ⚠️

2. Optional Services (7) - Based on `*_ENABLED` Vars

⚠️ GitHub.com Fallback ⚠️