nkapp host

The nkapp host command suite provides comprehensive tools for managing network routing, SSL trust, and remote server bootstrapping for your Nanokit environments.

nkapp host <subcommand> [options]

Subcommands

host add

Add or update a domain mapping in your nanokit.yml configuration. This command dynamically updates the configuration file and maps domains to either the entire project (root gateway) or specific services.

Usage:

nkapp host add <env> [service] <domain>

Examples:

# Map a domain to the 'api' service in the 'local' environment
nkapp host add local api api.my-app.localhost

# Map a domain globally for the whole project (acts as a default for all envs)
nkapp host add global my-app.com

# Map a domain to the 'web' service globally
nkapp host add global web my-app.com

How it works:

• When adding a project-level host (e.g. global my-app.com), it updates the host property at the root of nanokit.yml or inside an environment block.
• When adding a service-level host (e.g. local api api.my-app.local), it updates the host property of that specific service.

---

host del (alias: rm)

Remove an existing domain mapping from your nanokit.yml.

Usage:

nkapp host del <env> <arg>

Examples:

# Remove the domain mapping for the 'api' service in the local environment
nkapp host del local api

# Remove the globally configured project domain
nkapp host del global my-domain.com

How it works:

• If arg matches the name of a registered service, Nanokit will remove the host property from that service's configuration.
• If arg does not match any service, Nanokit assumes you are removing the project-level host configuration.

---

host trust

Install the Nanokit Root CA (Certificate Authority) into your system's certificate trust store. This enables secure HTTPS (Green Lock) without browser security warnings when using self-signed certificates locally or on private remote environments.

Usage:

nkapp host trust [-e <env>]

Flag	Type	Default	Description
-e, --env <env>	string	local	The environment to trust. Can be local or remote environments (e.g., stage, test-aws).

Why is this needed? Nanokit uses Caddy with automatic HTTPS for local development and private .local routing. To avoid "Your connection is not private" errors in modern browsers, your operating system needs to trust the Root CA that Nanokit generated.

Cross-Platform Support:

Platform	Trust Method
macOS	Automatically added to the System Keychain via security add-trusted-cert.
Linux	Added to /usr/local/share/ca-certificates and NSS databases (for Chrome/Firefox) via certutil.
WSL2	Full Bridge: Installs in the Linux store AND automatically propagates to the Windows User Certificate Store using certutil.exe.

Trusting Remote Environments: If you have deployed a staging environment on AWS or a VPS that uses an internal/private .local domain, Nanokit will securely fetch the Root CA from the remote gateway via SSH or HTTP before installing it on your local machine.

# Trust your remote staging environment
nkapp host trust -e stage

Note: You may need to fully restart your browser for the changes to the system trust store to take effect.

---

host setup

Bootstrap a remote VPS for deployment. This command prepares a raw server to be managed by Nanokit.

Usage:

nkapp host setup <env>

Prerequisites: The environment specified must have a deploy.target defined in nanokit.yml. For example:

environments:
  stage:
    deploy:
      target: root@123.45.67.89

What it does: When you run nkapp host setup stage, Nanokit will:

1. Connect to the remote host via SSH.
2. Install the Docker Engine and its dependencies if they are missing.
3. Configure the UFW firewall to allow HTTP (80), HTTPS (443), and SSH (22) traffic.
4. Create the necessary Nanokit project directory structure at /opt/nanokit/projects/<project-name>.

Tip.Automatic Bootstrapping: You rarely need to run host setup manually. The nkapp deploy command includes an automatic bootstrap check and will perform these steps if it detects the server is uninitialized.

---

host certs-fix (alias: certificates-fix)

Repair SSL/TLS certificate permissions on a remote VPS and restart the affected services (the Caddy gateway and, when present, the mail service).

Usage:

nkapp host certs-fix <env>

Use this when HTTPS on a remote environment breaks after a manual change on the server (e.g. certificates owned by the wrong user, or a gateway that cannot read its certificate files).

---

host task-recover

Recover a container that Docker reports as stopped while its containerd task is still running. This can happen when the Docker daemon is killed (for example by the out-of-memory killer) and restarts without reconnecting to a container's shim. Docker then shows the container as Exited (128), docker start fails with AlreadyExists, and docker rm fails with cannot delete running task.

Usage:

nkapp host task-recover <env> [container] [--dry-run] [-y] [--json] [--strict] [--timeout <seconds>] [--no-start]

What it does:

1. Runs one read-only check on the host. It compares Docker's container list with containerd's task list (ctr -n moby task ls). A container counts as orphaned only when Docker says it is stopped and containerd has a running task with the same full container id.
2. Shows the plan. --dry-run stops here. Without -y it asks for confirmation.
3. For each orphaned container it stops the stale task (SIGTERM, then SIGKILL if needed), deletes it, and starts the container again. If the container has a restart policy, Docker gets 5 seconds to restart it first. --no-start deletes the task and leaves the container stopped.
4. Checks the host again and reports the result. If a container is still orphaned, or did not come back, the command exits with code 1.

It refuses, and changes nothing, when ctr is not installed, when either list cannot be read, when a task is in a state it does not recognise, or when [container] is a partial id, matches no container, or matches several. Pass the exact container name or its full 64-character id. It never touches a container Docker still reports as running.

Flag	Default	Description
--dry-run	false	Show the plan, change nothing
-y, --yes	false	Skip the confirmation prompt
--json	false	Print one JSON document on stdout. Requires -y unless --dry-run is set
--strict	false	Also exit 1 when --dry-run finds an orphaned container, or when a running task has no Docker container
--timeout <seconds>	10	How long to wait after SIGTERM before SIGKILL (1 to 300)
--no-start	—	Delete the stale task but leave the container stopped

Like host setup, it needs a deploy.target for the environment and a Nanokit plan that allows remote environments.