Skip to content

ENVIRONMENT_VARIABLES

Jump to bottom
GitHub Actions Bot edited this page May 3, 2026 · 3 revisions

nself-admin Environment Variables Reference

Overview

This document provides a complete reference for all environment variables used by nself-admin, aligned with the official nself Environment Variable Specification v1.0.

Table of Contents

  1. Core Configuration
  2. Service Enable Flags
  3. Database Configuration
  4. Hasura Configuration
  5. Authentication Service
  6. Storage Service (MinIO)
  7. Optional Services
  8. Custom Services
  9. Frontend Applications
  10. Backup Configuration
  11. Email Configuration
  12. Monitoring Bundle
  13. Environment File Cascade
  14. Migration Guide

Core Configuration

Basic project settings that define your nself deployment.

Variable Type Default Required Description
ENV string dev Yes Environment mode (dev, staging, prod)
PROJECT_NAME string - Yes Project identifier (alphanumeric + dash)
PROJECT_DESCRIPTION string "" No Human-readable project description
BASE_DOMAIN string local.nself.org Yes Base domain for all services
ADMIN_EMAIL string "" No Administrative contact email

Examples

ENV=dev
PROJECT_NAME=my-awesome-app
PROJECT_DESCRIPTION="E-commerce platform with multi-tenant support"
BASE_DOMAIN=local.nself.org
ADMIN_EMAIL=admin@mycompany.com

Service Enable Flags

Control which services are included in your stack. Core services default to true for backward compatibility.

Core Services (Always Required)

Variable Type Default Description
POSTGRES_ENABLED bool true PostgreSQL database (always required)
HASURA_ENABLED bool true Hasura GraphQL engine (always required)
AUTH_ENABLED bool true Authentication service (recommended)
STORAGE_ENABLED bool true MinIO storage service (recommended)

Optional Services

Variable Type Default Description
NSELF_ADMIN_ENABLED bool false Enable nself-admin UI
REDIS_ENABLED bool false Enable Redis cache
MAILPIT_ENABLED bool false Enable development email capture
FUNCTIONS_ENABLED bool false Enable serverless functions (coming soon)
PROMETHEUS_ENABLED bool false Enable Prometheus metrics
GRAFANA_ENABLED bool false Enable Grafana dashboards
LOKI_ENABLED bool false Enable log aggregation
SEARCH_ENABLED bool false Enable search services

Bundle Flags

Variable Type Default Description
MONITORING_ENABLED bool false Enables Prometheus, Grafana, and Loki together

Example

# Core services (these default to true)
POSTGRES_ENABLED=true
HASURA_ENABLED=true
AUTH_ENABLED=true
STORAGE_ENABLED=true

# Optional services
NSELF_ADMIN_ENABLED=true
REDIS_ENABLED=true
MAILPIT_ENABLED=true

# Monitoring bundle (sets all 3 monitoring services)
MONITORING_ENABLED=true

Database Configuration

PostgreSQL database settings.

Variable Type Default Required Description
POSTGRES_DB string nself Yes Database name
POSTGRES_USER string postgres Yes Database user (always postgres)
POSTGRES_PASSWORD string nself-dev-password Yes Database password
POSTGRES_HOST string postgres No Database host
POSTGRES_PORT int 5432 No Database port
POSTGRES_VERSION string 16-alpine No PostgreSQL version
POSTGRES_EXTENSIONS string uuid-ossp,pgcrypto No Comma-separated extensions

Example

POSTGRES_DB=myapp_db
POSTGRES_PASSWORD=super-secret-password-here
POSTGRES_VERSION=16-alpine
POSTGRES_EXTENSIONS=uuid-ossp,pgcrypto,postgis

Hasura Configuration

Hasura GraphQL engine settings.

Variable Type Default Required Description
HASURA_VERSION string v2.44.0 No Hasura version
HASURA_GRAPHQL_ADMIN_SECRET string - Yes Admin secret (min 32 chars)
HASURA_JWT_KEY string - Yes JWT secret key (min 32 chars)
HASURA_JWT_TYPE string HS256 No JWT algorithm (HS256, RS256)
HASURA_GRAPHQL_ENABLE_CONSOLE bool true (dev) No Enable web console
HASURA_GRAPHQL_DEV_MODE bool true (dev) No Development mode
HASURA_GRAPHQL_ENABLE_TELEMETRY bool false No Send usage stats
HASURA_GRAPHQL_CORS_DOMAIN string * (dev) No CORS domains
HASURA_GRAPHQL_UNAUTHORIZED_ROLE string public No Default unauthorized role

Important Notes

  • HASURA_JWT_KEY and HASURA_JWT_TYPE are used to build the HASURA_GRAPHQL_JWT_SECRET JSON
  • Both secrets MUST be at least 32 characters long
  • In production, use strong randomly generated secrets

Example

HASURA_GRAPHQL_ADMIN_SECRET=my-very-long-secret-key-minimum-32-characters-long
HASURA_JWT_KEY=another-very-long-secret-key-minimum-32-chars
HASURA_JWT_TYPE=HS256
HASURA_GRAPHQL_ENABLE_CONSOLE=false  # Disable in production
HASURA_GRAPHQL_DEV_MODE=false        # Disable in production
HASURA_GRAPHQL_CORS_DOMAIN=https://myapp.com,https://api.myapp.com

Authentication Service

Hasura Auth service configuration.

Variable Type Default Description
AUTH_VERSION string v0.36.0 Auth service version
AUTH_JWT_REFRESH_TOKEN_EXPIRES_IN int 2592000 Refresh token lifetime (seconds)
AUTH_JWT_ACCESS_TOKEN_EXPIRES_IN int 900 Access token lifetime (seconds)
AUTH_WEBAUTHN_ENABLED bool false Enable passwordless auth
AUTH_EMAIL_VERIFICATION_REQUIRED bool false Require email verification

Example

AUTH_JWT_ACCESS_TOKEN_EXPIRES_IN=900      # 15 minutes
AUTH_JWT_REFRESH_TOKEN_EXPIRES_IN=2592000 # 30 days
AUTH_EMAIL_VERIFICATION_REQUIRED=true     # Require email verification
AUTH_WEBAUTHN_ENABLED=true               # Enable passwordless login

Storage Service (MinIO)

Object storage configuration.

Variable Type Default Required Description
STORAGE_ENABLED bool true No Enable storage service
MINIO_VERSION string latest No MinIO version
MINIO_ROOT_USER string minioadmin Yes* Root username
MINIO_ROOT_PASSWORD string - Yes* Root password (min 8 chars)
MINIO_PORT int 9000 No MinIO API port
MINIO_CONSOLE_PORT int 9001 No MinIO console port
S3_BUCKET string nself No Default bucket name

*Required if STORAGE_ENABLED=true

Example

STORAGE_ENABLED=true
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=secure-password-here
S3_BUCKET=myapp-storage

Optional Services

Redis Configuration

Variable Type Default Description
REDIS_ENABLED bool false Enable Redis cache
REDIS_VERSION string 7-alpine Redis version
REDIS_PORT int 6379 Redis port
REDIS_PASSWORD string "" Redis password

Search Services

Variable Type Default Description
SEARCH_ENABLED bool false Enable search service
SEARCH_ENGINE string meilisearch Search engine choice

Available search engines:

  • meilisearch - Default, best for most use cases
  • typesense - High performance, typo-tolerant
  • zinc - Lightweight Elasticsearch alternative
  • elasticsearch - Industry standard
  • opensearch - AWS fork of Elasticsearch
  • sonic - Ultra-lightweight option

Example

# Redis
REDIS_ENABLED=true
REDIS_PASSWORD=redis-password-here

# Search
SEARCH_ENABLED=true
SEARCH_ENGINE=meilisearch

Custom Services

Custom services that run as part of the Docker stack.

Format

SERVICES_ENABLED=true
CS_1=name:framework:port:route
CS_2=name:framework:port:route

Pattern

name:framework[:port][:route]

  • name - Service name (required)
  • framework - Framework/language (required)
  • port - Service port (optional, default 4000+)
  • route - URL route/subdomain (optional)

Additional Configuration

CS_1_MEMORY=512M
CS_1_CPU=0.5
CS_1_REPLICAS=2
CS_1_TABLE_PREFIX=api_
CS_1_HEALTHCHECK=/health
CS_1_PUBLIC=true
CS_1_RATE_LIMIT=100r/s

Example

SERVICES_ENABLED=true

# API service
CS_1=api:express:4000:api
CS_1_MEMORY=1G
CS_1_CPU=1.0
CS_1_TABLE_PREFIX=api_

# Worker service
CS_2=worker:python:4001
CS_2_MEMORY=512M

# Analytics service
CS_3=analytics:go:4002:analytics
CS_3_PUBLIC=true

Frontend Applications

Configure external frontend applications that consume your backend.

Format 1: Individual Variables (Recommended)

FRONTEND_APP_COUNT=2

# App 1
FRONTEND_APP_1_DISPLAY_NAME=Admin Dashboard
FRONTEND_APP_1_SYSTEM_NAME=admin_dashboard
FRONTEND_APP_1_TABLE_PREFIX=admin_
FRONTEND_APP_1_PORT=3001  # REQUIRED for nginx routing
FRONTEND_APP_1_ROUTE=admin
FRONTEND_APP_1_REMOTE_SCHEMA_NAME=admin_schema
FRONTEND_APP_1_REMOTE_SCHEMA_URL=http://localhost:4001/graphql

# App 2
FRONTEND_APP_2_DISPLAY_NAME=Customer Portal
FRONTEND_APP_2_SYSTEM_NAME=customer_portal
FRONTEND_APP_2_TABLE_PREFIX=customer_
FRONTEND_APP_2_PORT=3002  # REQUIRED
FRONTEND_APP_2_ROUTE=portal

Variables

Pattern Type Required Description
FRONTEND_APP_COUNT int Yes Number of frontend apps
FRONTEND_APP_N_DISPLAY_NAME string No Human-readable name
FRONTEND_APP_N_SYSTEM_NAME string No System identifier (no spaces)
FRONTEND_APP_N_TABLE_PREFIX string No Database table prefix
FRONTEND_APP_N_PORT int Yes Local development port
FRONTEND_APP_N_ROUTE string No Subdomain/route
FRONTEND_APP_N_REMOTE_SCHEMA_NAME string No Hasura remote schema name
FRONTEND_APP_N_REMOTE_SCHEMA_URL string No GraphQL endpoint URL

Port Requirements

  • Ports are REQUIRED for nginx routing
  • Use unique ports (3001, 3002, 3003, etc.)
  • Avoid conflicts with service ports

Backup Configuration

Automated backup settings.

Variable Type Default Description
BACKUP_ENABLED bool false Enable automated backups
BACKUP_SCHEDULE string 0 2 * * * Cron schedule
BACKUP_RETENTION_DAYS int 30 Days to retain backups
BACKUP_DIR string ./backups Backup directory
BACKUP_STORAGE string local Storage location
BACKUP_TYPES string database Backup types
BACKUP_COMPRESSION bool true Enable compression
BACKUP_ENCRYPTION bool false Enable encryption
BACKUP_CLOUD_PROVIDER string "" Cloud provider

Cron Schedule Examples

  • 0 2 * * * - Daily at 2 AM
  • 0 */6 * * * - Every 6 hours
  • 0 0 * * 0 - Weekly on Sunday
  • 0 0 1 * * - Monthly on the 1st

Example

BACKUP_ENABLED=true
BACKUP_SCHEDULE=0 2 * * *      # Daily at 2 AM
BACKUP_RETENTION_DAYS=30       # Keep for 30 days
BACKUP_COMPRESSION=true        # Compress backups
BACKUP_ENCRYPTION=true         # Encrypt backups
BACKUP_CLOUD_PROVIDER=s3       # Store in S3

Email Configuration

Development (Mailpit)

EMAIL_PROVIDER=mailpit
MAILPIT_ENABLED=true
MAILPIT_SMTP_PORT=1025
MAILPIT_UI_PORT=8025

Production Options

EMAIL_PROVIDER=sendgrid  # Options: sendgrid, aws-ses, mailgun, postmark, etc.

SMTP Configuration

When EMAIL_PROVIDER=smtp:

AUTH_SMTP_HOST=smtp.example.com
AUTH_SMTP_PORT=587
AUTH_SMTP_USER=username
AUTH_SMTP_PASS=password
AUTH_SMTP_SECURE=true
AUTH_SMTP_SENDER=noreply@example.com

Supported Providers

  • SendGrid
  • AWS SES
  • Mailgun
  • Postmark
  • Gmail (with app password)
  • Office365
  • Brevo (Sendinblue)
  • Resend
  • SparkPost
  • Custom SMTP

Monitoring Bundle

Enable full monitoring with a single flag or individual services.

Bundle Flag

MONITORING_ENABLED=true  # Enables all three services

Individual Flags

PROMETHEUS_ENABLED=true
GRAFANA_ENABLED=true
LOKI_ENABLED=true

Monitoring Ports

  • Prometheus: 9090
  • Grafana: 3000
  • Loki: 3100

Environment File Cascade

Files are loaded in this exact order (later overrides earlier):

  1. .env.dev - Team development defaults (committed to git)
  2. .env.staging - Staging overrides (only if ENV=staging)
  3. .env.prod - Production config (only if ENV=prod)
  4. .env.secrets - Production secrets (only if ENV=prod, never commit)
  5. .env - Local overrides (highest priority, never commit)

Best Practices

  • Team defaults: Write to .env.dev
  • Personal overrides: Write to .env
  • Production secrets: Use .env.secrets
  • Never commit: .env, .env.secrets
  • Always commit: .env.dev, .env.staging, .env.prod

Migration Guide

From Old Variable Names

Old Variable New Variable Notes
NADMIN_ENABLED NSELF_ADMIN_ENABLED Use new name
MINIO_ENABLED STORAGE_ENABLED Storage service control
DB_BACKUP_* BACKUP_* Remove DB_ prefix
ELASTICSEARCH_ENABLED SEARCH_ENABLED Generic search flag
USER_SERVICE_* CS_* New service pattern
HASURA_GRAPHQL_JWT_SECRET HASURA_JWT_KEY + HASURA_JWT_TYPE Split into two vars

Example Migration

Old Format

NADMIN_ENABLED=true
MINIO_ENABLED=true
DB_BACKUP_ENABLED=true
DB_BACKUP_SCHEDULE=0 2 * * *
ELASTICSEARCH_ENABLED=true
USER_SERVICE_1_NAME=api
HASURA_GRAPHQL_JWT_SECRET={"type":"HS256","key":"secret-key"}

New Format

NSELF_ADMIN_ENABLED=true
STORAGE_ENABLED=true
BACKUP_ENABLED=true
BACKUP_SCHEDULE=0 2 * * *
SEARCH_ENABLED=true
CS_1=api:express:4000:api
HASURA_JWT_KEY=secret-key
HASURA_JWT_TYPE=HS256

Validation Rules

Required Variables

  • PROJECT_NAME - Must be set
  • HASURA_GRAPHQL_ADMIN_SECRET - Minimum 32 characters
  • HASURA_JWT_KEY - Minimum 32 characters
  • MINIO_ROOT_PASSWORD - Minimum 8 characters (if storage enabled)

Port Uniqueness

All ports must be unique. Reserved ports:

  • 80/443: Nginx
  • 3000: Hasura Console
  • 3100: nself-admin
  • 4000: Auth
  • 5432: PostgreSQL
  • 6379: Redis
  • 8080: Hasura GraphQL
  • 9000/9001: MinIO
  • 9090: Prometheus
  • 3000: Grafana

Naming Conventions

  • Service names: lowercase, alphanumeric + dash
  • Table prefixes: lowercase, alphanumeric + underscore, end with underscore
  • Routes: lowercase, alphanumeric + dash
  • Project names: lowercase, alphanumeric + dash + underscore

Complete Example

Development Environment

# Core Configuration
ENV=dev
PROJECT_NAME=my-awesome-app
PROJECT_DESCRIPTION="Multi-tenant SaaS platform"
BASE_DOMAIN=localhost
ADMIN_EMAIL=admin@localhost

# Core Services (defaults shown for clarity)
POSTGRES_ENABLED=true
HASURA_ENABLED=true
AUTH_ENABLED=true
STORAGE_ENABLED=true

# Database
POSTGRES_DB=myapp
POSTGRES_PASSWORD=dev-password-only

# Hasura
HASURA_GRAPHQL_ADMIN_SECRET=development-admin-secret-minimum-32-chars
HASURA_JWT_KEY=development-jwt-key-minimum-32-characters
HASURA_JWT_TYPE=HS256

# Optional Services
NSELF_ADMIN_ENABLED=true
REDIS_ENABLED=true
MAILPIT_ENABLED=true
SEARCH_ENABLED=true
SEARCH_ENGINE=meilisearch

# Custom Services
SERVICES_ENABLED=true
CS_1=api:express:4000:api
CS_2=worker:python:4001

# Frontend Apps
FRONTEND_APP_COUNT=2
FRONTEND_APP_1_DISPLAY_NAME=Admin Portal
FRONTEND_APP_1_PORT=3001
FRONTEND_APP_1_ROUTE=admin
FRONTEND_APP_2_DISPLAY_NAME=Customer App
FRONTEND_APP_2_PORT=3002
FRONTEND_APP_2_ROUTE=app

# Backups
BACKUP_ENABLED=true
BACKUP_SCHEDULE=0 2 * * *

Production Environment

# Core Configuration
ENV=prod
PROJECT_NAME=my-awesome-app
BASE_DOMAIN=myapp.com
ADMIN_EMAIL=ops@myapp.com

# Security (use strong secrets!)
HASURA_GRAPHQL_ADMIN_SECRET=<generate-strong-64-char-secret>
HASURA_JWT_KEY=<generate-strong-64-char-secret>
HASURA_GRAPHQL_ENABLE_CONSOLE=false
HASURA_GRAPHQL_DEV_MODE=false
HASURA_GRAPHQL_CORS_DOMAIN=https://myapp.com,https://api.myapp.com

# Storage
MINIO_ROOT_PASSWORD=<strong-password>

# Email
EMAIL_PROVIDER=sendgrid
AUTH_SMTP_HOST=smtp.sendgrid.net
AUTH_SMTP_USER=apikey
AUTH_SMTP_PASS=<sendgrid-api-key>
AUTH_SMTP_SENDER=noreply@myapp.com

# Monitoring
MONITORING_ENABLED=true

# Backups
BACKUP_ENABLED=true
BACKUP_RETENTION_DAYS=90
BACKUP_ENCRYPTION=true
BACKUP_CLOUD_PROVIDER=s3

Troubleshooting

Common Issues

  1. Services not starting: Check that required variables are set
  2. Port conflicts: Ensure all ports are unique
  3. Authentication failures: Verify secret lengths (32+ chars)
  4. Storage issues: Check MINIO_ROOT_PASSWORD is 8+ chars
  5. Frontend routing issues: Ensure PORT is set for each app

Debug Commands

# Check loaded environment
cat .env.dev

# Verify service status
docker-compose ps

# Check logs
docker-compose logs <service-name>

# Test environment cascade
echo $PROJECT_NAME

Additional Resources

Last Updated: 2025-01-05 Spec Version: 1.0.0

Version: 1.0.0 | Updated: 2026-10-19 11:40 UTC | GitHub

Navigation

Home

Getting Started

Core Features

Reference

Deployment

Help & Support

Meta

Clone this wiki locally