Skip to main content

Local Development Setup

This guide walks you through building and running DockNimbus locally on a single machine for development and testing.

Prerequisites​

  • Go 1.22+ (to build from source)
  • Docker (for compute instances, K3s clusters, RustFS, and EasyHAProxy)
  • Linux (agent metrics use Linux syscalls; API and CLI work on macOS too)

Optional:

  • WireGuard — only needed for multi-node mesh networking

Build​

cd docknimbus
make build

This produces three binaries in bin/:

  • nimbus-api — the control plane server
  • nimbus-agent — the node agent
  • nimbus — the CLI

Start the API server​

./bin/nimbus-api --config configs/api.yaml

The server starts on :8443 with TLS (auto-generated self-signed certificate) and a local SQLite database (nimbus.db).

Leave this running in a terminal.

Bootstrap and configure​

In a new terminal:

# Bootstrap the admin user (also saves CA cert to ~/.nimbus/ca.crt)
./bin/nimbus bootstrap --api-url https://localhost:8443

# Configure the CLI with the returned credentials
./bin/nimbus configure \
  --api-url https://localhost:8443 \
  --access-key NBUSxxxxxxxxxxxxxxxxxxxx \
  --secret-key yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

The CLI automatically uses ~/.nimbus/ca.crt (saved by bootstrap) to trust the self-signed certificate.

If you bootstrapped with curl and don't have the CA cert yet:

curl -sk https://localhost:8443/v1/ca -o ~/.nimbus/ca.crt

Add a local node​

sudo ./bin/nimbus node add --local --ip <your-local-ip>

This creates the node record, issues an mTLS client certificate, downloads the agent binary, and starts the agent via systemd.

Verify​

./bin/nimbus node list
ID              NAME  IP             STATUS  ROLE  AGENT  CPU        MEMORY
node-xxxxxxxx         192.168.1.x    ready   -     dev    8000/8000  16384MB/16384MB

Adding remote nodes​

For multi-node setups:

./bin/nimbus node add \
  --ip 192.168.1.10 \
  --user root \
  --api-url https://YOUR_API_HOST:8443

This automatically:

  1. Pre-creates a node record and issues a client certificate
  2. Downloads the agent binary from the API server
  3. Copies binary, CA cert, and client cert/key to the remote machine via SSH
  4. Installs WireGuard if missing (Docker is installed automatically only when the node is assigned to a Docker Swarm)
  5. Writes the agent config and starts the systemd service
  6. Waits for the node to become ready

Nodes form a full-mesh WireGuard VPN automatically.

Try it out​

With your node ready, try the workflows in the Guides section, using ./bin/nimbus instead of the installed binary.

Cross-compilation​

GOOS=linux GOARCH=arm64 make build    # ARM64
make build-cross                         # All platforms

Deploying a development build​

To install your build on an existing control plane, or to run it in the foreground on the control plane itself, use the helpers described in Development Scripts.