nkapp deploy

Deploy your application directly to a VPS via SSH. Optimized for Linux servers with automated bootstrap, ephemeral key support, and selective service targeting.


nkapp deploy [service] [options]

Options

Flag	Type	Default	Description
`-e, --env <env>`	string	`stage`	Target environment
`--ssh <host>`	string	—	SSH connection string (e.g., `root@192.168.1.1`). Overrides `deploy.target` in config.
`-p, --port <port>`	number	`22`	SSH port
`-s, --service <name>`	string	—	Deploy only a specific service (alias for positional)
`--rollback`	boolean	`false`	Rollback to the previous state
`-y, --yes`	boolean	`false`	Skip confirmation prompts

Workflow

1. Load & Resolve

Configuration is loaded, environment overrides are merged, and all secrets are resolved — including the deploy.sshKey field itself, which can be a vault:// URI.

2. SSH Connection

Nanokit connects to the target host using the resolved credentials.

3. VPS Bootstrap Check

If Docker is not installed on the remote host, Nanokit offers to automatically bootstrap the VPS:

Installs Docker Engine
Configures UFW firewall (opens ports 80, 443)
Creates the Nanokit project directory structure

4. Code Synchronization

Project files are synced to /opt/nanokit/projects/<name>/ on the remote host using the configured method:

rsync (default): Incremental file sync, respects .gitignore
git: Remote git pull from your repository

5. SSL Factory Reset

If public domains are detected (.app, .dev), Nanokit purges stale Caddy certificates to ensure fresh ACME challenges.

6. Service Orchestration

The Reconciler runs on the remote Docker daemon to create/update containers.

Ephemeral SSH Keys

Nanokit supports in-memory SSH keys resolved from Vault. If the sshKey value contains a raw PEM key (from vault://), Nanokit:

Writes it to a temporary file with 0600 permissions
Uses it for the SSH connection
Deletes it immediately after deployment


deploy:
  target: root@185.47.172.104
  sshKey: "vault://infra/ssh#private_key"

Deploy only a single service without touching the rest of the stack using the positional argument (recommended) or the flag:


# Recommended
nkapp deploy api -e stage
 
# Also supported
nkapp deploy -e stage -s api

Examples


# Deploy to staging using config defaults
nkapp deploy -e stage
 
# Deploy to a specific host (override config)
nkapp deploy --ssh root@10.0.0.5 -p 2222
 
# Deploy only the API service
nkapp deploy api -e production -y
 
# Rollback to previous state
nkapp deploy -e stage --rollback

[!WARNING] The --rollback flag reverts to the previous reconciler state. It does not revert code changes on the remote host.