nself doctor

Diagnose your nSelf installation. Checks system requirements, configuration, Docker health, SSL certificates, and network. Automatically fixes common problems with --fix.

Quick start

# Full diagnostics
nself doctor

# Deep mode — full security hardening suite (free, no license)
nself doctor --deep

# Auto-fix detected issues
nself doctor --fix

# Check one category
nself doctor --category ssl

Synopsis

nself doctor [FLAGS]

Description

nself doctor runs a suite of checks across six categories: system requirements, configuration, Docker health, SSL certificates, network, and services. Each check reports pass, warning, or fail. Failed checks with --fix are auto-remediated where possible.

--deep extends the standard check suite with the full security hardening scan (RLS validation, rate limit verification, SSRF guard, JWT key rotation readiness, WAF baseline, encryption-at-rest config, audit log availability). This scan is free — it never checks a license.

In production, critical findings from --deep block deploys unless --force is passed with a written justification. Use --json to integrate doctor output into CI pipelines or alerting.

Flags

Diagnostic categories

Examples

Standard diagnostic

nself doctor
# System Requirements    ✓ 5 passed
# Configuration         ✓ 6 passed, ⚠ 1 warning
# Docker Health         ✓ 5 passed
# SSL Certificates      ✓ 5 passed
# Network               ✓ 4 passed
# ───────────────────────────────────
# 25 passed, 1 warning, 0 failed
# Run 'nself doctor --fix' to resolve 1 warning

Deep security scan

nself doctor --deep
# (all standard checks, plus:)
# Security Hardening    ✓ RLS enabled on all np_* tables
#                       ✓ Rate limits configured
#                       ✓ SSRF guard active
#                       ⚠ JWT rotation overdue (last rotated 187 days ago)
#                       ✓ Audit log enabled

Auto-fix in CI

nself doctor --fix --json > doctor.json
exit_code=$?
if [ $exit_code -eq 2 ]; then
  echo "Critical issues remain after auto-fix"
  cat doctor.json | jq '.categories | to_entries[] | select(.value.status == "failed")'
  exit 1
fi

Skip SSL checks (CI without local DNS)

nself doctor --skip ssl,network

Check production environment

nself doctor --env prod
# Production-specific checks:
# - Let's Encrypt certificate (not mkcert)
# - DEBUG disabled
# - Strong password requirements enforced

JSON output schema

nself doctor --json
{
  "timestamp": "2026-05-07T14:22:00Z",
  "summary": { "passed": 25, "warnings": 1, "failed": 0, "total": 26 },
  "categories": {
    "ssl": {
      "status": "passed",
      "checks": [
        {
          "name": "cert_valid",
          "status": "passed",
          "message": "Certificate valid for local.nself.org",
          "fixable": false
        }
      ]
    }
  }
}

Auto-fixable checks

Exit codes

• 0 — all checks passed (warnings are not failures)
• 1 — warnings detected
• 2 — critical failures detected
• 3 — doctor itself failed to run

Related

• nself dev bootstrap — one-shot setup that runs doctor at the end
• nself deploy — runs doctor before every remote deploy
• nself dns-setup — fix DNS resolution issues detected by doctor
• Security Guide — full hardening documentation