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>]

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:

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.