Skip to Content
Getting Started

Getting Started with Nanokit

Nanokit is a developer-first container orchestration platform built around a single config file — nanokit.yml. This guide walks you from zero to a running local environment, then all the way through staging and production deployment.

Prerequisites

Before you begin, make sure the following are in place:

RequirementNotes
DockerMust be running locally. Used by nkapp up -e local.
nkapp CLIInstall via npm install -g @nkapp/cli or your package manager of choice.
SSH key pairRequired for VPS-based environments (staging, production).
A VPSAny Linux server accessible over SSH. Root access is recommended for first-time bootstrapping.

[!NOTE] You do not need Kubernetes or any cloud provider to get started. Nanokit runs on plain Docker — locally and on remote servers.

Step 1 — Initialize Your Project

Navigate to your project root and run:

nkapp init

This scaffolds a nanokit.yml file in the current directory with sensible defaults derived from your project structure.

If you prefer an interactive setup wizard, use nkapp configure instead:

nkapp configure

nkapp configure walks you through naming your project, defining services, and setting up environment targets one by one. It is the recommended path if you are new to Nanokit.

[!TIP] Run nkapp configure again at any time to interactively update your configuration. Changes are merged into the existing nanokit.yml — nothing is overwritten without your confirmation.

Step 2 — Understand nanokit.yml

nanokit.yml is the single source of truth for your entire project. It defines your services and how they behave across every environment.

Here is a realistic minimal example:

name: my-app
 
services:
  api:
    runtime: node
    port: 3000
    start: node dist/index.js
    host: api.my-app.localhost
    env:
      NODE_ENV: development
 
environments:
  local:
    infra:
      provider: docker
    services:
      api:
        start: npm run dev
 
  stage:
    infra:
      provider: docker
    deploy:
      target: root@185.47.172.104
      sshKey: ~/.ssh/id_rsa
      method: rsync
      prepare: npm ci && npm run build
    services:
      api:
        host: api.my-app.com
        env:
          NODE_ENV: production

Key concepts:

  • services — the top-level block defines service defaults shared across all environments. Each service gets a runtime, a port, a start command, and an optional host for routing.
  • environments.local — overrides for local development. Here, api uses npm run dev (hot-reload) instead of the production start command. The provider: docker means Nanokit manages everything through local Docker.
  • environments.stage — adds a deploy block pointing to a remote VPS. The prepare command runs on the server before containers are started. Service-level overrides (like host and env) replace the defaults for this environment only.
  • Environment promotion — the same nanokit.yml governs all environments. You promote by targeting a different environment, not by maintaining separate config files.

[!IMPORTANT] Never commit secrets directly into nanokit.yml. Use the env block for non-sensitive values and manage secrets separately with nkapp secrets.

Step 3 — Start Local Development

With your nanokit.yml in place, bring up your local environment:

nkapp up -e local

Nanokit will:

  1. Parse nanokit.yml and resolve the local environment block.
  2. Pull or build required Docker images.
  3. Start all services as containers on an auto-managed bridge network (nk-<project>-local-bridge).
  4. Start the Caddy gateway and configure HTTPS routing to each service’s .localhost domain.

Your API will be reachable at https://api.my-app.localhost (or whatever host you configured) within seconds. If a service has no explicit host, Nanokit derives one automatically as <service>.<project>.localhost.

Trust the local HTTPS certificate

The Caddy gateway issues certificates for .localhost domains from a local Nanokit Root CA. On first run, your browser may warn you. To silence the warning permanently, install the Root CA into your system trust store with one command:

nkapp host trust

This works on macOS (System Keychain), Linux (update-ca-certificates + NSS databases for Chrome/Firefox), and WSL2 (also propagates to the Windows certificate store). Fully restart your browser afterwards. See nkapp host trust for details.

Open the Hub

The Nanokit Hub dashboard auto-starts alongside nkapp up. To open it manually:

nkapp hub

The Hub gives you a live view of running containers, resource usage, and log streams for every service in your project.

Step 4 — Run a Health Check

Before you start building in earnest, verify your environment is fully healthy:

nkapp doctor

nkapp doctor inspects your setup and reports on:

  • System architecture support (x64 / arm64)
  • Docker daemon reachability and version
  • nanokit.yml syntax and schema validity
  • Gateway / infrastructure status for the current project
  • Mail delivery configuration (when configured)
  • CLI freshness (whether a newer @nkapp/cli is available)

[!WARNING] Always run nkapp doctor when switching machines or after a Docker/system update. It catches the majority of “why won’t it start” issues before they become time sinks.

Fix any issues flagged by doctor before proceeding. Each problem comes with a suggested remediation step.

Step 5 — Useful Local Commands

Once your stack is running locally, these commands cover the most common day-to-day operations:

Tail logs from a service

nkapp logs api

Stream live log output from a container. Press Ctrl+C to stop tailing.

Open a shell inside a container

nkapp shell api

Drops you into an interactive shell inside the running api container. Useful for one-off commands, inspecting the filesystem, or debugging.

Stop all local services

nkapp stop -e local

Gracefully stops all containers for the local environment without removing them — restart instantly with nkapp start. To remove the containers (and the project network and gateway), use nkapp destroy; volumes and images are preserved either way.

[!TIP] Use nkapp stop / nkapp destroy rather than raw docker commands — they ensure the Caddy gateway and project resources are managed consistently.

Step 6 — Deploy to Staging

When your local work is ready for a shared environment, deploy to your staging VPS.

Configure the stage environment

Make sure the stage block in your nanokit.yml is populated (see Step 2). At minimum you need:

environments:
  stage:
    infra:
      provider: docker
    deploy:
      target: root@<your-vps-ip>
      sshKey: ~/.ssh/id_rsa
      method: rsync
      prepare: npm ci && npm run build
    services:
      api:
        host: api.my-app.com
        env:
          NODE_ENV: production

Preview what will change

Before applying any changes to a remote environment, run a dry-run to see exactly what Nanokit would do:

nkapp plan -e stage

This shows added, modified, and removed services without touching the server.

Bootstrap and deploy

nkapp up -e stage

On first run, nkapp up -e stage:

  1. SSHes into the target server using your configured key.
  2. Installs Docker on the VPS if not already present.
  3. Creates the bridge network (nk-my-app-stage-bridge).
  4. Rsyncs your project code to the server.
  5. Runs the prepare command on the server (npm ci && npm run build).
  6. Starts all containers and configures the Caddy gateway for your production-style domains.

Subsequent runs of nkapp up -e stage are incremental — only changed services are restarted.

Pull resolved secrets locally

If your project references remote secrets (e.g. vault:// URIs), resolve them into a local .env file:

nkapp secrets pull            # writes .env (local environment)
nkapp secrets pull -e stage   # writes .env.stage

These files contain resolved plain-text values — keep them in .gitignore and never commit them.

Step 7 — Iterate with nkapp deploy

Full nkapp up cycles are for bootstrapping. For day-to-day iterative changes, use:

nkapp deploy -e stage

nkapp deploy is a faster loop:

  1. Rsyncs only changed files to the server.
  2. Runs the prepare command.
  3. Rebuilds and restarts only the affected containers.

It skips infrastructure provisioning and gateway reconfiguration, making it significantly faster than a full up.

# Typical iterative workflow
git add .
git commit -m "fix: handle empty state in /api/items"
nkapp deploy -e stage
nkapp logs api          # confirm the fix is live

[!TIP] Wire nkapp deploy -e stage into your CI pipeline on pushes to develop for zero-friction continuous staging deployments.

Step 8 — Promote to Production

When staging has been validated, promote your changes to production:

nkapp plan -e production    # dry-run first
nkapp up -e production      # bootstrap, or:
nkapp deploy -e production  # fast iteration on existing prod

Production environments follow the same structure as staging. Add a production block to nanokit.yml pointing to your production server(s):

environments:
  production:
    infra:
      provider: docker
    deploy:
      target: root@<prod-ip>
      sshKey: ~/.ssh/id_rsa_prod
      method: rsync
      prepare: npm ci && npm run build
    services:
      api:
        host: api.my-app.com
        env:
          NODE_ENV: production

[!CAUTION] Always run nkapp plan -e production and review the output before running nkapp up -e production or nkapp deploy -e production. Changes to production are applied immediately. If a deploy goes wrong, nkapp deploy -e production --rollback reverts to the previous reconciler state (it does not revert code changes on the remote host).

Multi-Environment Workflow at a Glance

Local (Docker)  →  Staging (VPS)  →  Production (VPS)
  nkapp up          nkapp up          nkapp up
  -e local          -e stage          -e production
                  nkapp deploy      nkapp deploy
                  -e stage          -e production

All three environments are driven by the same nanokit.yml. Environment-specific overrides (hosts, env vars, deploy targets) live in their respective environments.<name> blocks. There are no separate config files to keep in sync.

Next Steps

InstallationCLI Overview