Build Command

v0.4.8Updated for ɳSelf v0.4.8

The nself build command generates all configuration files needed to run your ɳSelf infrastructure. This includes Docker Compose files, nginx configurations, SSL certificates, and service-specific configs.

Build Process Overview

- Docker Compose: Generates docker-compose.yml from .env configuration
- Nginx: Creates reverse proxy configs for all services and routes
- SSL: Generates self-signed certificates or prepares Let's Encrypt
- Monitoring: Creates Prometheus, Grafana, and alerting configs
- Custom Services: Scaffolds CS_N service directories

Usage

nself build [options]

Options

Option	Description	Default
`--validate`	Validate configuration before building	false
`--dry-run`	Preview generated files without writing	false
`--force`	Overwrite existing files without prompting	false
`--clean`	Remove generated files before building	false
`--env NAME`	Build for specific environment	current
`--verbose, -v`	Show detailed output	false
`--quiet, -q`	Suppress non-essential output	false

Examples

Basic Build

# Build all configuration files
nself build

# Build with validation
nself build --validate

# Preview without writing files
nself build --dry-run

Environment-Specific Builds

# Build for staging environment
nself build --env staging

# Build for production
nself build --env prod

# Clean and rebuild
nself build --clean --force

Generated Files

The build command generates the following file structure:

project/
+-- docker-compose.yml       # Main Docker Compose configuration
+-- nginx/
|   +-- nginx.conf           # Main nginx configuration
|   +-- conf.d/
|       +-- default.conf     # Default server block
|       +-- api.conf         # Hasura GraphQL routing
|       +-- auth.conf        # Authentication service routing
|       +-- storage.conf     # MinIO routing (if enabled)
|       +-- search.conf      # MeiliSearch routing (if enabled)
|       +-- admin.conf       # Admin UI routing (if enabled)
|       +-- custom-*.conf    # Custom service routes (CS_N)
|       +-- frontend-*.conf  # Frontend app routes
+-- postgres/
|   +-- init/
|       +-- 00-init.sql      # Database initialization
+-- ssl/
|   +-- certificates/
|       +-- local.crt        # SSL certificate
|       +-- local.key        # SSL private key
|       +-- ca.crt           # CA certificate (local dev)
+-- monitoring/              # If MONITORING_ENABLED=true
|   +-- prometheus/
|   |   +-- prometheus.yml   # Prometheus configuration
|   |   +-- alerts/          # Alert rules
|   +-- grafana/
|   |   +-- provisioning/    # Dashboard provisioning
|   +-- loki/
|       +-- loki-config.yml  # Loki configuration
+-- services/                # Custom services (CS_N)
    +-- ping_api/            # Example custom service
        +-- Dockerfile
        +-- src/
            +-- index.ts

Build Stages

The build process executes these stages in order:

Stage	Description	Output
1. Validate	Check .env configuration	Errors if invalid
2. Docker Compose	Generate service definitions	docker-compose.yml
3. Nginx	Generate reverse proxy configs	nginx/*.conf
4. SSL	Generate or verify certificates	ssl/certificates/
5. PostgreSQL	Generate init scripts	postgres/init/
6. Monitoring	Generate monitoring configs	monitoring/
7. Custom Services	Scaffold service directories	services/

Docker Compose Generation

The generated docker-compose.yml includes:

Required Services (Always Included)

services:
  postgres:     # PostgreSQL database
  hasura:       # Hasura GraphQL Engine
  auth:         # nHost Authentication
  nginx:        # Reverse proxy with SSL

Optional Services (Based on .env)

# Enabled with REDIS_ENABLED=true
  redis:        # Redis cache

# Enabled with MINIO_ENABLED=true
  minio:        # S3-compatible storage

# Enabled with MEILISEARCH_ENABLED=true
  meilisearch:  # Full-text search

# Enabled with MAILPIT_ENABLED=true
  mailpit:      # Email testing (dev only)

# Enabled with NSELF_ADMIN_ENABLED=true
  nself-admin:  # Admin UI

# Enabled with MONITORING_ENABLED=true
  prometheus:   # Metrics collection
  grafana:      # Dashboards
  loki:         # Log aggregation
  promtail:     # Log shipping
  alertmanager: # Alert management

Nginx Configuration

The build generates nginx configs based on your routing configuration:

# .env configuration
BASE_DOMAIN=local.nself.org
HASURA_ROUTE=api
AUTH_ROUTE=auth
MINIO_ROUTE=storage

# Generated routes:
# https://api.local.nself.org    -> hasura:8080
# https://auth.local.nself.org   -> auth:4000
# https://storage.local.nself.org -> minio:9000

Frontend App Routing

# .env configuration
FRONTEND_APP_1_NAME=org
FRONTEND_APP_1_PORT=3010
FRONTEND_APP_1_ROUTE=org

# Generated route:
# https://org.local.nself.org -> host.docker.internal:3010

Custom Service Routing

# .env configuration
CS_1=ping_api:express-ts:8001
CS_1_ROUTE=ping
CS_1_PUBLIC=true

# Generated route:
# https://ping.local.nself.org -> ping_api:8001

SSL Certificate Generation

SSL certificates are generated based on environment:

Environment	Method	Tool
dev/local	Self-signed with local CA	mkcert
staging	Let's Encrypt (staging)	certbot
prod	Let's Encrypt (production)	certbot

Certificate Domains

Certificates automatically include:

# Always included
BASE_DOMAIN                  # e.g., local.nself.org
*.BASE_DOMAIN                # e.g., *.local.nself.org

# Service subdomains (if enabled)
api.BASE_DOMAIN              # Hasura
auth.BASE_DOMAIN             # Authentication
storage.BASE_DOMAIN          # MinIO
search.BASE_DOMAIN           # MeiliSearch
admin.BASE_DOMAIN            # Admin UI
mail.BASE_DOMAIN             # Mailpit

# Custom service routes
[CS_N_ROUTE].BASE_DOMAIN     # Custom services

# Frontend app routes
[FRONTEND_APP_N_ROUTE].BASE_DOMAIN  # Frontend apps

Monitoring Configuration

When MONITORING_ENABLED=true, the build generates:

Prometheus

# prometheus/prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
  - job_name: 'node'
  - job_name: 'cadvisor'
  - job_name: 'postgres'
  - job_name: 'redis'    # if enabled
  - job_name: 'hasura'

Grafana Dashboards

# Auto-provisioned dashboards:
- System Overview (CPU, Memory, Disk)
- PostgreSQL Metrics
- Hasura Performance
- Redis Stats (if enabled)
- Container Metrics (cAdvisor)

Build Validation

Use --validate to check configuration before building:

nself build --validate

# Validation checks:
# + Required variables present
# + Port conflicts detected
# + Service dependencies satisfied
# + Route conflicts detected
# + SSL certificate validity
# + Password strength (production)

# Example output:
  ➞ Validating configuration...

  ✓ PROJECT_NAME configured
  ✓ BASE_DOMAIN configured
  ✓ No port conflicts
  ✓ Service dependencies satisfied
  ! Warning: POSTGRES_PASSWORD is weak (< 12 chars)
  ✓ No route conflicts

  ⚠ Build would succeed with 1 warning(s)

Dry Run Mode

Preview generated files without writing:

nself build --dry-run

# Output shows:
# - Files that would be created
# - Files that would be modified
# - Configuration summary

# Example:
  ➞ Dry run mode - no files will be written

  Files to create:
    + docker-compose.yml
    + nginx/nginx.conf
    + nginx/conf.d/api.conf
    + nginx/conf.d/auth.conf
    + ssl/certificates/local.crt
    + ssl/certificates/local.key

  Files to modify:
    ~ postgres/init/00-init.sql (exists, will update)

  Summary:
    Create: 6 files
    Modify: 1 file
    Skip: 0 files

Build Output

nself build

# Typical output:
  ➞ Building ɳSelf project...

  Environment: local
  Base Domain: local.nself.org

  [1/7] Validating configuration... ✓
  [2/7] Generating Docker Compose... ✓
        - 8 services configured
        - 3 networks defined
        - 5 volumes defined
  [3/7] Generating nginx configs... ✓
        - 6 server blocks
        - SSL enabled
  [4/7] Generating SSL certificates... ✓
        - Domains: local.nself.org, *.local.nself.org
        - Valid until: 2027-01-24
  [5/7] Generating PostgreSQL init... ✓
  [6/7] Generating monitoring configs... ✓
        - Prometheus scrape targets: 6
        - Grafana dashboards: 4
  [7/7] Scaffolding custom services... ✓
        - ping_api (express-ts)

  ✓ Build complete!

  Next steps:
    nself start     # Start all services
    nself urls      # View service URLs

Rebuilding After Changes

After modifying .env, rebuild to apply changes:

# Edit configuration
vim .env

# Rebuild
nself build

# Restart affected services
nself restart

# Or rebuild and restart in one step
nself build && nself restart

Common Use Cases

Adding a New Service

# 1. Enable in .env
echo "REDIS_ENABLED=true" >> .env

# 2. Rebuild
nself build

# 3. Start
nself start redis

Adding a Frontend App

# 1. Add to .env
FRONTEND_APP_2_NAME=docs
FRONTEND_APP_2_PORT=3011
FRONTEND_APP_2_ROUTE=docs

# 2. Rebuild nginx configs
nself build

# 3. Restart nginx to pick up changes
nself restart nginx

Adding a Custom Service

# 1. Add to .env
CS_2=my_api:fastify-ts:8002
CS_2_ROUTE=my-api
CS_2_PUBLIC=true

# 2. Build (scaffolds service directory)
nself build

# 3. Develop your service
cd services/my_api
npm install
# Edit src/index.ts

# 4. Start
nself start

Troubleshooting

Build Fails with Validation Errors

# Check configuration
nself config validate

# Common issues:
# - Missing required variables
# - Invalid port numbers
# - Duplicate routes

SSL Certificate Issues

# Regenerate certificates
rm -rf ssl/certificates
nself build

# Trust the CA (macOS)
ɳSelf trust

Port Conflicts

# Check for conflicts
nself build --validate

# View current port usage
docker compose ps

# Change port in .env and rebuild
# HASURA_PORT=8081  # Instead of default 8080

Related Commands

Config Commands - Configuration management
Core Commands - Start/stop/restart services
Status Command - Service status
URLs Command - List service URLs
SSL Configuration - SSL setup guide