Staging Commands

v0.4.8Updated for nself v0.4.8

The nself staging command provides a complete workflow for staging environment management. Initialize staging servers, deploy full-stack applications, manage test data, and sync from production.

Staging Environment Features

- Full Stack Deploy: Backend + frontend apps on single VPS
- Test Data: Seed staging with mock data for QA
- Production Sync: Copy production data with anonymization
- Reset Capability: Quick environment reset for testing
- GitHub Sync: Auto-deploy from main or dev branch

Usage

nself staging <subcommand> [options]

Subcommands

Command	Description
`init`	Initialize staging environment configuration
`deploy`	Deploy to staging server
`seed`	Load test data into staging database
`sync`	Sync data from production
`reset`	Reset staging environment
`secrets`	Manage staging secrets
`logs`	View staging server logs
`shell`	SSH into staging server
`status`	Check staging deployment status

nself staging init

Initialize staging environment with server configuration.

nself staging init <domain> [options]

# Options:
#   --email EMAIL        Admin email for SSL certificates
#   --server HOST        Staging server hostname or IP
#   --user USER          SSH username (default: deploy)
#   --key PATH           SSH key path (default: ~/.ssh/nself_staging)
#   --port PORT          SSH port (default: 22)
#   --deploy-path PATH   Remote deployment path (default: /opt/nself)

# Examples:
nself staging init staging.example.com --email admin@example.com
nself staging init staging.myapp.com --server 167.235.233.65 --user deploy

Generated Files

.environments/staging/
+-- .env                # Staging configuration
+-- .env.secrets        # Sensitive credentials (chmod 600)
+-- server.json         # SSH connection details

server.json Format

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

Staging .env Defaults

ENV=staging
BASE_DOMAIN=staging.example.com
DEBUG=true
LOG_LEVEL=info

# SSL with Let's Encrypt staging
SSL_ENABLED=true
SSL_PROVIDER=letsencrypt
LETSENCRYPT_STAGING=true

# Hasura console enabled for debugging
HASURA_GRAPHQL_DEV_MODE=true
HASURA_GRAPHQL_ENABLE_CONSOLE=true

# Admin UI available for debugging
NSELF_ADMIN_ENABLED=true

# Monitoring enabled
MONITORING_ENABLED=true

nself staging deploy

Deploy to staging server. By default includes frontend apps (unlike production).

nself staging deploy [options]

# Options:
#   --dry-run            Preview deployment without executing
#   --force              Skip confirmation prompts
#   --backend-only       Exclude frontend apps
#   --skip-health        Skip health checks after deployment
#   --rolling            Use rolling deployment (zero-downtime)
#   --branch BRANCH      Deploy specific git branch (default: main)

# Examples:
nself staging deploy                    # Deploy full stack
nself staging deploy --dry-run          # Preview deployment
nself staging deploy --backend-only     # Backend services only
nself staging deploy --branch dev       # Deploy dev branch

Deployment Process

# What happens during staging deploy:

1. Validate SSH access to staging server
2. Run local 'nself build' to generate configs
3. Sync files via rsync:
   - docker-compose.yml
   - nginx/
   - postgres/
   - services/
   - monitoring/
   - ssl/
   - .env + .env.secrets
4. Sync frontend apps (unless --backend-only):
   - org/
   - docs/
   - cloud/
   - chat/
5. Run 'docker compose pull && docker compose up -d'
6. Build and start frontend apps via PM2
7. Run health checks
8. Display deployment summary

Deployment Output

nself staging deploy

# Output:
  ➞ Deploying to staging...

  Environment: staging
  Server: staging.example.com
  Branch: main

  [1/8] Checking SSH access... ✓
  [2/8] Building configuration... ✓
  [3/8] Syncing backend files... ✓
        - 156 files synced
  [4/8] Syncing frontend apps... ✓
        - org, docs, cloud, chat
  [5/8] Deploying backend services... ✓
        - 8 containers updated
  [6/8] Building frontend apps... ✓
        - 4 apps built
  [7/8] Starting frontend apps... ✓
        - PM2 processes started
  [8/8] Running health checks... ✓
        - All endpoints responding

  ✓ Deployment complete!

  URLs:
    GraphQL:    https://api.staging.example.com
    Auth:       https://auth.staging.example.com
    Admin:      https://admin.staging.example.com
    org:        https://staging.example.com
    docs:       https://docs.staging.example.com

nself staging seed

Load test data into staging database for QA testing.

nself staging seed [file] [options]

# Options:
#   --force              Re-seed even if data exists
#   --truncate           Clear existing data before seeding
#   --users COUNT        Number of mock users to create (default: 100)

# Examples:
nself staging seed                      # Auto-detect seed file
nself staging seed ./seeds/qa-data.sql  # Use specific file
nself staging seed --users 500          # Create 500 mock users
nself staging seed --truncate           # Clear and re-seed

Auto-Detected Seed Files

# The command looks for seed files in this order:
1. nself/seeds/staging/
2. seeds/staging.sql
3. seed/staging.sql
4. data/seed-staging.sql

Seed Structure

nself/seeds/
+-- common/              # Always runs first
|   +-- 01_categories.sql
|   +-- 02_settings.sql
+-- staging/             # Staging-specific data
    +-- 01_test_users.sql
    +-- 02_sample_data.sql
    +-- 03_qa_scenarios.sql

Mock User Generation

# Staging creates 100 mock users by default:

User Pattern:
  Email:      testuser{N}@staging.example.com
  Password:   TestUser123!
  Roles:      user (90%), admin (10%)

# Access mock users:
testuser1@staging.example.com / TestUser123!
testuser2@staging.example.com / TestUser123!
...
testadmin1@staging.example.com / TestUser123!  # admin role

nself staging sync

Sync data from production to staging for realistic testing.

nself staging sync [target] [options]

# Targets:
#   db                   Sync database only
#   files                Sync storage files only
#   all                  Sync everything (default)

# Options:
#   --anonymize          Anonymize PII data (recommended)
#   --force              Skip confirmation
#   --exclude TABLES     Exclude specific tables (comma-separated)
#   --since DATE         Only sync data since date

# Examples:
nself staging sync                      # Sync all with anonymization prompt
nself staging sync db --anonymize       # Sync database with anonymization
nself staging sync files                # Sync MinIO storage files
nself staging sync --exclude audit_logs,sessions

Anonymization

# When --anonymize is used, PII is replaced:

Original                        Anonymized
--------                        ----------
john.doe@company.com     ->     user_a1b2c3@staging.local
John Doe                 ->     User A1B2C3
+1-555-123-4567          ->     +1-555-000-0000
123 Main Street          ->     [REDACTED]

# Anonymization patterns (configurable in .env):
ANONYMIZE_PATTERNS='email,phone,address,name,ssn,credit_card'

Sync Output

nself staging sync db --anonymize

# Output:
  ➞ Syncing production data to staging...

  ⚠ WARNING: This will REPLACE staging data with production data.
  ? Continue? (y/N) y

  [1/5] Creating production backup... ✓
        - Size: 2.3 GB
  [2/5] Transferring to staging... ✓
        - Transfer time: 45s
  [3/5] Restoring database... ✓
  [4/5] Anonymizing PII data... ✓
        - 15,432 email addresses anonymized
        - 8,291 phone numbers anonymized
        - 12,156 names anonymized
  [5/5] Verifying data integrity... ✓

  ✓ Sync complete!

  Records synced:
    users:         15,432
    orders:        89,201
    products:      1,245
    ...

nself staging reset

Reset staging environment to clean state.

nself staging reset [options]

# Options:
#   --data               Also delete all data (database, storage)
#   --force              Skip confirmation
#   --keep-secrets       Preserve .env.secrets

# Examples:
nself staging reset                     # Restart services, keep data
nself staging reset --data              # Full reset including data
nself staging reset --force             # Skip confirmation

Reset Levels

Command	Services	Database	Storage	Config
`reset`	Restart	Keep	Keep	Keep
`reset --data`	Restart	Delete	Delete	Keep

nself staging secrets

Manage staging environment secrets.

nself staging secrets <action> [options]

# Actions:
#   generate             Generate all secrets
#   show                 Show secrets (masked)
#   show --reveal        Show secrets (unmasked)
#   rotate KEY           Rotate specific secret

# Examples:
nself staging secrets generate
nself staging secrets show
nself staging secrets show --reveal
nself staging secrets rotate POSTGRES_PASSWORD

Generated Secrets

# Secrets generated for staging:

POSTGRES_PASSWORD          # 32-char random
HASURA_GRAPHQL_ADMIN_SECRET # 32-char random
JWT_SECRET                 # 64-char random (RS256)
COOKIE_SECRET              # 32-char random
MINIO_ROOT_PASSWORD        # 32-char random
REDIS_PASSWORD             # 32-char random (if Redis enabled)
GRAFANA_ADMIN_PASSWORD     # 16-char random (if monitoring enabled)

# Stored in .environments/staging/.env.secrets
# File permissions: 600 (owner read/write only)

nself staging logs

View logs from staging server.

nself staging logs [service] [options]

# Options:
#   -f, --follow         Follow log output
#   -n, --tail LINES     Number of lines to show (default: 100)
#   --since DURATION     Show logs since (e.g., 1h, 30m)

# Examples:
nself staging logs                      # All services
nself staging logs hasura               # Hasura logs only
nself staging logs -f                   # Follow all logs
nself staging logs nginx --tail 50      # Last 50 nginx lines
nself staging logs --since 1h           # Last hour of logs

nself staging shell

SSH into staging server or container.

nself staging shell [service]

# Examples:
nself staging shell                     # SSH to server
nself staging shell postgres            # Shell into postgres container
nself staging shell hasura              # Shell into hasura container

# Once connected:
# - Check Docker status: docker compose ps
# - View logs: docker compose logs
# - Run commands: docker compose exec postgres psql

nself staging status

Check staging deployment status.

nself staging status [options]

# Options:
#   --verbose            Detailed status
#   --json               JSON output

# Example output:
  ➞ Staging Status

  Server: staging.example.com
  Last Deploy: 2026-01-24 10:30:00 (2 hours ago)
  Branch: main (commit: abc1234)

  Backend Services:
    postgres        running     healthy
    hasura          running     healthy
    auth            running     healthy
    nginx           running     -
    redis           running     healthy
    minio           running     healthy

  Frontend Apps:
    org             running     PM2 online
    docs            running     PM2 online
    cloud           running     PM2 online
    chat            running     PM2 online

  Resources:
    CPU: 23%  |  Memory: 4.2 GB / 8 GB  |  Disk: 45 GB / 100 GB

  ✓ All services healthy

Complete Staging Workflow

Initial Setup

# 1. Initialize staging environment
nself staging init staging.myapp.com \
  --email admin@myapp.com \
  --server 167.235.233.65

# 2. Configure SSH access
# Edit .environments/staging/server.json with credentials
# Ensure SSH key exists at ~/.ssh/nself_staging

# 3. Generate secrets
nself staging secrets generate

# 4. Verify SSH access
nself deploy check-access

First Deployment

# 1. Preview deployment
nself staging deploy --dry-run

# 2. Deploy
nself staging deploy

# 3. Seed test data
nself staging seed

# 4. Verify deployment
nself staging status
nself urls --env staging

Ongoing Development

# Deploy updates
nself staging deploy

# View logs during testing
nself staging logs -f

# SSH in for debugging
nself staging shell

# Reset for fresh testing
nself staging reset --data
nself staging seed

Pre-Production Testing

# Sync production data for realistic testing
nself staging sync db --anonymize

# Run tests against staging
npm test -- --env staging

# Compare staging vs production config
nself env diff staging prod

# When ready, promote to production
nself deploy prod

Staging vs Production

Aspect	Staging	Production
Frontend Apps	Included by default	Excluded (Vercel)
Admin UI	Enabled	Disabled
Hasura Console	Enabled	Disabled
Debug Mode	Enabled	Disabled
Log Level	info	warning
SSL	Let's Encrypt (staging)	Let's Encrypt (prod)
Mock Data	100 test users	Real users only
Data Sync	From production	N/A

Troubleshooting

Deployment Fails

# Check SSH access
nself deploy check-access

# Verify server.json configuration
cat .environments/staging/server.json

# Test SSH manually
ssh -i ~/.ssh/nself_staging deploy@staging.example.com

# Check remote Docker status
nself staging shell
docker compose ps

Services Not Starting

# Check logs
nself staging logs

# Check specific service
nself staging logs hasura

# SSH and investigate
nself staging shell
docker compose logs --tail 100

Frontend Apps Not Building

# SSH to server
nself staging shell

# Check PM2 status
pm2 list

# View build logs
pm2 logs org

# Rebuild manually
cd /opt/nself/org
npm install
npm run build
pm2 restart org

Related Commands

Deploy Commands - General deployment
Production Commands - Production hardening
Environment Commands - Environment management
Database Commands - Database operations