Environment Commands

Updated for nself v0.4.8

The nself env command provides comprehensive environment management for creating, switching, and managing multiple deployment environments.

Synopsis

nself env <subcommand> [options]

Subcommands

Environment Structure

Each environment is stored in .environments/<name>/ with the following structure:

.environments/
├── local/
│   ├── .env              # Environment configuration
│   ├── .env.secrets      # Secrets (600 permissions, git-ignored)
│   └── server.json       # Local only - no SSH needed
├── staging/
│   ├── .env              # Staging config (DEBUG=false, staging domain)
│   ├── .env.secrets      # Staging secrets (chmod 600)
│   └── server.json       # SSH connection: host, user, key, port
└── prod/
    ├── .env              # Production config (strict settings)
    ├── .env.secrets      # Production secrets (chmod 600, strong only)
    └── server.json       # Production SSH connection details

Core Commands

nself env create

Create a new environment configuration from a template.

nself env create <name> [template] [--force]

# Arguments:
#   name     - Environment name (sanitized to lowercase alphanumeric with hyphens)
#   template - Base template: local, staging, or prod (default: local)

# Options:
#   --force, -f  - Overwrite existing environment

# Examples
nself env create dev                    # Create local dev environment
nself env create staging staging        # Create staging environment
nself env create production prod        # Create production environment
nself env create qa staging             # Create QA from staging template

nself env list

List all available environments with the current active environment marked.

nself env list

# Example output:
# ENVIRONMENTS
# * local (current)
#   staging
#   prod

nself env switch

Switch to a different environment and apply its configuration.

nself env switch <name> [--quiet]

# What happens when switching:
# 1. Current .env files are backed up to .env-backups/
# 2. Environment-specific config is merged and applied to .env.local
# 3. Current environment marker is updated in .current-env

# Examples
nself env switch staging
nself env switch production

nself env status

Show current environment status including domain, services, and connection status.

nself env status

# Displays:
# - Current active environment
# - Domain configuration
# - Enabled services
# - Server connection status (for remote environments)

nself env info

Show detailed information about an environment (secrets are masked).

nself env info [name]

# Arguments:
#   name - Environment name (default: current environment)

# Examples
nself env info staging
nself env info         # Show current environment

nself env diff

Compare two environments side-by-side.

nself env diff <env1> <env2> [--values]

# Options:
#   --values - Show actual values (secrets are masked)

# Examples
nself env diff staging production
nself env diff dev staging --values

# Example output:
# COMPARING: staging vs prod
#
# KEY                     staging              prod
# ENV                     staging              prod
# DEBUG                   false                false
# BASE_DOMAIN             staging.example.com  example.com
# NSELF_ADMIN_ENABLED     true                 false  ← Different

nself env validate

Validate an environment's configuration.

nself env validate [name]

# Checks:
# ✓ Required environment variables are present
# ✓ Server configuration is valid
# ✓ Secrets file exists and has correct permissions
# ✓ Referenced files exist

nself env delete

Delete an environment configuration.

nself env delete <name> [--force]

# Note: Cannot delete the currently active environment

# Examples
nself env delete qa
nself env delete staging --force

nself env export

Export an environment as a tarball (secrets can be excluded).

nself env export <name> [--output <file>]

# Options:
#   --output, -o - Output filename (default: <name>-env.tar.gz)

# Examples
nself env export staging
nself env export prod --output prod-backup.tar.gz

nself env import

Import an environment from a tarball.

nself env import <file> [--name <name>]

# Options:
#   --name - Override the environment name

# Examples
nself env import staging-env.tar.gz
nself env import backup.tar.gz --name staging-restored

Configuration Files

.env File

Contains non-sensitive environment configuration:

ENV=staging
DEBUG=false
BASE_DOMAIN=staging.example.com
SSL_ENABLED=true
POSTGRES_DB=myproject_staging

.env.secrets File

Contains sensitive secrets (automatically set to 600 permissions):

POSTGRES_PASSWORD=<secret>
HASURA_GRAPHQL_ADMIN_SECRET=<secret>
JWT_SECRET=<secret>

server.json File

Contains remote server connection details:

{
  "name": "staging",
  "type": "staging",
  "host": "staging.example.com",
  "port": 22,
  "user": "deploy",
  "key": "~/.ssh/staging_key",
  "deploy_path": "/opt/nself"
}

Environment Cascade

When an environment is active, configuration is loaded in this order (later values override earlier):

# Load order:
1. .env.dev            # Base development config
2. .environments/<name>/.env    # Environment-specific config
3. .env.local          # Generated merged config
4. .env.secrets        # Secrets

Environment Templates

Local Template

Optimized for development with relaxed security:

# .environments/local/.env
ENV=dev
DEBUG=true
BASE_DOMAIN=local.nself.org
LOG_LEVEL=debug

# Services enabled for development
NSELF_ADMIN_ENABLED=true
MAILPIT_ENABLED=true
MONITORING_ENABLED=false  # Faster startup

Staging Template

Production-like configuration for testing:

# .environments/staging/.env
ENV=staging
DEBUG=false
BASE_DOMAIN=staging.example.com
LOG_LEVEL=info

# Full service stack
NSELF_ADMIN_ENABLED=true  # Keep for debugging
MONITORING_ENABLED=true

Production Template

Hardened configuration for production deployment:

# .environments/prod/.env
ENV=prod
DEBUG=false
BASE_DOMAIN=example.com
LOG_LEVEL=warning

# Security hardened
NSELF_ADMIN_ENABLED=false  # Disabled in production
HASURA_GRAPHQL_DEV_MODE=false
HASURA_GRAPHQL_ENABLE_CONSOLE=false
MONITORING_ENABLED=true

Typical Workflows

Initial Setup

# Create all environments
nself env create local local
nself env create staging staging
nself env create prod prod

# Configure server connections
vim .environments/staging/server.json
vim .environments/prod/server.json

# Validate all
nself env validate local
nself env validate staging
nself env validate prod

Daily Development

# Check current environment
nself env status

# Ensure you're on local
nself env switch local

# Start development
nself build && nself start

Staging Deployment

# Compare current vs staging
nself env diff local staging

# Switch to staging
nself env switch staging

# Validate and deploy
nself env validate staging
nself build
nself deploy staging

Production Release

# Validate production config
nself env validate prod

# Compare staging vs prod
nself env diff staging prod

# Switch and deploy
nself env switch prod
nself prod harden
nself deploy prod

Best Practices

• Never commit secrets: Add .environments/*/.env.secrets to .gitignore
• Use templates: Start from standard templates for consistency
• Validate before deploy: Always run nself env validate before deploying
• Back up secrets: Store production secrets securely outside git
• Set chmod 600 on secrets: Restrict file permissions for security

Next Steps

• Deployment Commands - Deploy to staging/production
• Production Commands - Production hardening
• Staging Commands - Staging environment management