NanokitDocs

Appearance

nkapp doctor ​

Run a comprehensive environment health check to verify that all prerequisites are met and the local Nanokit installation is correctly configured.

bash
nkapp doctor

doctor is a zero-argument command — just run it in the root of any Nanokit project (or without a project for system-level checks). It is strictly read-only: every check only ever inspects and counts, never removes or modifies anything.

What It Checks ​

doctor runs these diagnostic categories in order:

1. System Architecture ​

Reads the host OS and CPU architecture. Nanokit officially supports x64 and arm64 (Apple Silicon / AWS Graviton). A warning is emitted for any other architecture but execution continues.

2. Docker Health ​

Pings the local Docker daemon and prints the engine version and operating system.

ResultMeaning
✅ Docker Engine is runningDaemon is reachable and healthy
❌ Could not connectDocker Desktop / Docker Engine is not running or not installed

TIP

If Docker is not found, install Docker Desktop or run sudo systemctl start docker on Linux.

3. Configuration Audit ​

Locates nanokit.yml in the current directory and parses it against the local environment to validate syntax and schema. Errors here indicate YAML formatting issues or unknown configuration keys.

4. Infrastructure Status ​

Queries the local Docker provider for any running containers tagged with the current project name and environment. Reports whether the Gateway container is active, which is required for routing traffic to local services.

5. Cloud Deploy Preflight ​

For every non-local environment targeting a cloud provider (aws, gcp, azure, digitalocean), doctor reports the same validation the deploy path enforces — most importantly that a region resolves. Without one the provider silently defaults to us-east-1 and resources land somewhere you did not intend. Silent (one info line) when no cloud environments are configured.

6. Mail Delivery ​

If your project configures mail (a mail: block), doctor reports the mail delivery mode per environment and validates it against the target provider's capabilities — for example, mail.provider: selfhost on a non-Docker target is flagged, because only Docker/VPS targets can reconcile a self-hosted mail server. Silent when mail is not configured.

7. Container Hygiene ​

Counts the containers that nkapp containers prune would consider stale — exited or created, older than 24h, not declared in nanokit.yml, and not another project's — using the same selection predicate, so doctor and the prune command can never disagree.

CountResult
< 25✅ no significant accumulation
≥ 25⚠️ warning
≥ 500❌ error

It also reports how many of those carry no Nanokit labels at all and prints the exact command to run. That unlabeled class is typically cron job-run leftovers: the scheduler cannot label the containers it creates, so they are invisible to every label-scoped command and accumulate silently until the daemon runs out of resources.

This check exists precisely because that pile is visible long before anything breaks.

8. Image Space ​

The same idea for Docker images, reusing the nkapp images prune predicate. It reports the dangling and --unused scopes separately, each with its guaranteed reclaim.

Reclaimable (guaranteed)Result
< 5 GB✅ no significant accumulation
≥ 5 GB⚠️ warning
≥ 20 GB❌ error

Thresholds sit on the unique-byte figure, never the shared-inclusive total, so the check never promises space that would not actually come back. It also names how many more images are held back as this project's own registry build artifacts.

9. CLI Version ​

Reports whether your CLI is up to date, using the update-notifier cache (no extra network call). Warns if a newer @nkapp/cli is available (run nkapp update). When running the local dev binary it says so and skips the comparison.

Example Output ​

  Nanokit Doctor - Environment Health Check

  ℹ System: linux (x64)
  ✓ Architecture is fully supported.

  Docker Health
  ✓ Docker Engine is running.
    Version: 24.0.7
    Operating System: Docker Desktop

  Configuration Audit
  ✓ nanokit.yml is valid.

  Infrastructure Status
  ✓ Local Gateway is active.

  Cloud Deploy Preflight
  ℹ No cloud (aws/gcp/azure/digitalocean) environments configured.

  Container Hygiene
  ✓ No significant container accumulation (3 stale, threshold 25).

  Image Space
  ⚠ 9.4 GB of reclaimable image space (61 dangling, 74 total unused).
           → `nkapp images prune --dry-run` reclaims 9.4 GB from 61 dangling image(s) — the safe default.

  CLI Version
  ✓ CLI is up to date (v1.x.x).

  Diagnosis Summary
  ⚠ Environment is functional but has 1 warning(s).

Exit Behaviour ​

doctor always exits 0, even when errors are detected, so it can be safely included in scripts without breaking downstream steps. Inspect the printed summary to decide whether to proceed.

TIP

Run nkapp doctor whenever you encounter unexpected behaviour after installing Nanokit, updating Docker, or switching machines. It is the fastest way to rule out environment configuration issues.