Doctor Command

The nself doctor command diagnoses issues with your ɳSelf installation and environment. It checks system requirements, configuration, Docker health, SSL certificates, and can automatically fix common problems.

Usage

nself doctor [options]

Options

Diagnostic Categories

Examples

Full Diagnostic

# Run all checks
nself doctor

# Output:
  ➞ ɳSelf Doctor - Diagnosing your installation...

  System Requirements
  -------------------
  ✓ Docker 24.0.7 installed (minimum: 20.10)
  ✓ Docker Compose 2.23.0 installed (minimum: 2.0)
  ✓ Docker daemon is running
  ✓ Node.js 20.10.0 installed (minimum: 18.0)
  ✓ mkcert installed

  Configuration
  -------------
  ✓ .env file found
  ✓ PROJECT_NAME configured
  ✓ BASE_DOMAIN configured
  ✓ Required secrets present
  ! Warning: POSTGRES_PASSWORD is weak (< 12 chars)
  ✓ No port conflicts detected

  Docker Health
  -------------
  ✓ Docker daemon healthy
  ✓ 5 containers running
  ✓ All containers healthy
  ✓ Docker networks configured
  ✓ Docker volumes intact

  SSL Certificates
  ----------------
  ✓ Certificate valid for local.nself.org
  ✓ Certificate trusted in system
  ✓ Expires in 364 days

  Network
  -------
  ✓ Port 80 available
  ✓ Port 443 available
  ✓ DNS resolves local.nself.org -> 127.0.0.1

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Summary: 18 passed, 1 warning, 0 failed
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ 1 warning detected. Run 'nself doctor --fix' to resolve.

Auto-Fix Issues

# Automatically fix detected issues
nself doctor --fix

# Output:
  ➞ ɳSelf Doctor - Auto-fixing issues...

  ✗ Docker daemon not running
    → Starting Docker daemon... ✓

  ✗ SSL certificate expired
    → Regenerating certificates... ✓
    → Installing in trust store... ✓

  ✗ Port 80 in use by another process
    → Cannot auto-fix: Stop the conflicting process manually

  ✓ Fixed 2 of 3 issues
  ! 1 issue requires manual intervention

Check Specific Category

# Check only SSL certificates
nself doctor --category ssl

# Check only Docker health
nself doctor --category docker

# Check only configuration
nself doctor --category config

Verbose Output

nself doctor --verbose

# Shows additional details:
# - Exact version numbers
# - File paths checked
# - Network diagnostic details
# - Resource usage statistics

Check Details

System Requirements Checks

Configuration Checks

Docker Health Checks

SSL Certificate Checks

Network Checks

JSON Output

Get machine-readable output for scripting:

nself doctor --json

# Output:
{
  "timestamp": "2026-01-24T10:30:00Z",
  "summary": {
    "passed": 18,
    "warnings": 1,
    "failed": 0,
    "total": 19
  },
  "categories": {
    "system": {
      "status": "passed",
      "checks": [
        {
          "name": "docker_version",
          "status": "passed",
          "message": "Docker 24.0.7 installed",
          "details": { "version": "24.0.7", "minimum": "20.10" }
        }
      ]
    },
    "config": {
      "status": "warning",
      "checks": [
        {
          "name": "password_strength",
          "status": "warning",
          "message": "POSTGRES_PASSWORD is weak",
          "fixable": true
        }
      ]
    }
  }
}

Skip Specific Checks

# Skip SSL checks (useful in CI environments)
nself doctor --skip ssl

# Skip multiple categories
nself doctor --skip ssl,network

# Skip specific checks
nself doctor --skip docker_daemon,port_80

Environment-Specific Diagnostics

# Check staging environment
nself doctor --env staging

# Check production environment
nself doctor --env prod

# Different checks may apply:
# - Production: SSL must be Let's Encrypt
# - Production: DEBUG must be disabled
# - Production: Stronger password requirements

Exit Codes

Common Issues and Solutions

Docker Daemon Not Running

# Check detected:
✗ Docker daemon not running

# Auto-fix:
nself doctor --fix
# Or manually:
open -a Docker  # macOS
sudo systemctl start docker  # Linux

SSL Certificate Not Trusted

# Check detected:
✗ Certificate not trusted in system

# Auto-fix:
nself doctor --fix
# Or manually:
ɳSelf trust

Port Already in Use

# Check detected:
✗ Port 80 in use by process: nginx (pid 1234)

# Manual fix required:
# Option 1: Stop the conflicting process
sudo kill 1234

# Option 2: Change the port in .env
HTTP_PORT=8080
HTTPS_PORT=8443

Weak Passwords

# Check detected:
! POSTGRES_PASSWORD is weak (< 12 chars)

# Auto-fix:
nself doctor --fix
# Regenerates secrets with strong passwords

# Or manually regenerate:
ɳSelf prod secrets generate

Missing Configuration

# Check detected:
✗ .env file not found

# Auto-fix:
nself doctor --fix
# Creates .env from .env.example

# Or manually:
cp .env.example .env
# Then edit with your configuration

CI/CD Integration

# In GitHub Actions or CI pipeline:
- name: Check nself health
  run: |
    nself doctor --json > doctor-report.json
    if [ $? -eq 2 ]; then
      echo "Critical issues detected"
      cat doctor-report.json
      exit 1
    fi

# Skip network checks in CI (no localhost DNS)
- name: Check ɳSelf (CI mode)
  run: nself doctor --skip network,ssl

Related Commands

• Status Command - Service status overview
• Health Command - Health check monitoring
• Config Commands - Configuration validation
• Build Command - Rebuild configuration
• Troubleshooting Guide - Common issues