This document describes the configuration options available for the nself start command, including environment variables and command-line flags that control startup behavior.

The nself start command has been enhanced with smart defaults and configurable options to handle various deployment scenarios. All options are optional - the command works out of the box with sensible defaults.

These environment variables can be set in your .env file or exported in your shell to customize the start behavior:

• Default: smart
• Options: smart, fresh, force
• Description: Controls how containers are started
  • smart: Detects existing containers and resumes or recreates as needed
  • fresh: Always recreates containers (docker-compose up --force-recreate)
  • force: Forces recreation and removes orphans

# Example in .env
NSELF_START_MODE=smart

• Default: 120 (seconds)
• Range: 30-600
• Description: Maximum time to wait for health checks to pass

# Example: Wait up to 3 minutes for services to become healthy
NSELF_HEALTH_CHECK_TIMEOUT=180

• Default: 2 (seconds)
• Range: 1-10
• Description: How often to check service health status

# Example: Check every 5 seconds
NSELF_HEALTH_CHECK_INTERVAL=5

• Default: 80 (percent)
• Range: 0-100
• Description: Minimum percentage of services that must be healthy to consider start successful. Setting to 0 disables health check requirements.

# Example: Require only 60% of services to be healthy
NSELF_HEALTH_CHECK_REQUIRED=60

# Example: Disable health check requirements (always succeed)
NSELF_HEALTH_CHECK_REQUIRED=0

• Default: false
• Options: true, false
• Description: Skip all health checks and return immediately after starting containers

# Example: Skip health checks entirely
NSELF_SKIP_HEALTH_CHECKS=true

• Default: 300 (seconds)
• Range: 60-1800
• Description: Maximum time to wait for Docker image builds

# Example: Allow up to 10 minutes for building images
NSELF_DOCKER_BUILD_TIMEOUT=600

• Default: auto
• Options: auto, always, never
• Description: Controls container cleanup before starting
  • auto: Clean up only if containers are in error state
  • always: Always remove existing containers before starting
  • never: Never remove existing containers

# Example: Always start fresh
NSELF_CLEANUP_ON_START=always

• Default: 5
• Range: 1-20
• Description: Maximum number of containers to start in parallel

# Example: Start up to 10 containers at once
NSELF_PARALLEL_LIMIT=10

• Default: info
• Options: debug, info, warn, error
• Description: Controls verbosity of start command output

# Example: Show detailed debug information
NSELF_LOG_LEVEL=debug

These flags override environment variables when specified:

# Show help
nself start --help

# Verbose output (overrides NSELF_LOG_LEVEL)
nself start --verbose
nself start -v

# Debug mode (implies verbose)
nself start --debug
nself start -d

# Skip health checks
nself start --skip-health-checks

# Custom timeout (seconds)
nself start --timeout 180

# Set required healthy percentage
nself start --health-required 60

# Force recreate all containers
nself start --force-recreate
nself start --fresh

# Clean start (remove everything first)
nself start --clean-start

# Quick start (minimal checks)
nself start --quick

The default smart mode intelligently handles different scenarios:

1. No existing containers: Creates and starts all services
2. Stopped containers: Resumes existing containers
3. Running containers: Verifies health and reports status
4. Mixed state: Restarts stopped containers, keeps healthy running ones

# Uses smart mode by default
nself start

Forces recreation of all containers, useful when you've updated configurations:

# Via environment variable
NSELF_START_MODE=fresh nself start

# Via command flag
nself start --fresh

Most aggressive mode - removes everything and starts from scratch:

# Via environment variable
NSELF_START_MODE=force nself start

# Via command flag
nself start --force-recreate

The start command uses progressive health checking to provide better feedback:

1. Initial delay: Waits a few seconds for containers to initialize
2. Progressive monitoring: Shows which services become healthy over time
3. Partial success: Can succeed with partial health (default 80%)
4. Timeout handling: Doesn't fail if timeout reached but services are running

Different scenarios may require different health check strategies:

# Development: Be lenient with health checks
NSELF_HEALTH_CHECK_REQUIRED=60
NSELF_HEALTH_CHECK_TIMEOUT=60

# Production: Require all services healthy
NSELF_HEALTH_CHECK_REQUIRED=100
NSELF_HEALTH_CHECK_TIMEOUT=180

# Quick iteration: Skip health checks
NSELF_SKIP_HEALTH_CHECKS=true

Quick iteration with minimal checks:

# In .env
NSELF_START_MODE=smart
NSELF_HEALTH_CHECK_REQUIRED=60
NSELF_HEALTH_CHECK_TIMEOUT=60

Ensure clean state and full health:

# In CI script
export NSELF_START_MODE=fresh
export NSELF_HEALTH_CHECK_REQUIRED=100
export NSELF_HEALTH_CHECK_TIMEOUT=300
nself start

Maximum verbosity and no health requirements:

nself start --debug --skip-health-checks

Careful startup with full validation:

# In .env.production
NSELF_START_MODE=smart
NSELF_HEALTH_CHECK_REQUIRED=100
NSELF_HEALTH_CHECK_TIMEOUT=180
NSELF_CLEANUP_ON_START=auto
NSELF_LOG_LEVEL=info

Adjust the health check requirements:

# Lower the required percentage
NSELF_HEALTH_CHECK_REQUIRED=70

# Or increase timeout
NSELF_HEALTH_CHECK_TIMEOUT=180

Use cleanup options:

# Force cleanup
NSELF_CLEANUP_ON_START=always nself start

# Or use fresh mode
nself start --fresh

Optimize parallel limits and timeouts:

# Increase parallel starts
NSELF_PARALLEL_LIMIT=10

# Reduce health check interval
NSELF_HEALTH_CHECK_INTERVAL=1

The new start command is fully backward compatible. Existing workflows continue to work without any changes. The enhancements only activate when you explicitly set the environment variables or use the new command flags.

• Configuration Guide
• Environment Variables Reference
• Docker Compose Configuration
• Troubleshooting Guide