Get started: Single machine

Run both the CLI and the daemon on one Mac for local-dev or solo use.

This is the fastest path: install both binaries, run the daemon directly, and deploy from the same machine. Useful for trying StackPaaS out, building app templates, or running a personal PaaS on your own hardware.

Requirements

Install both binaries

brew tap stackcube/tap
brew install stackpaas stackpaasd

Initialize the daemon

Use your own SSH public key as the bootstrap admin and localhost as the daemon domain:

stackpaasd init \
  --admin-key ~/.ssh/id_ed25519.pub \
  --domain localhost

This writes ~/.stackpaasd/config.yml, generates the daemon's deploy key, registers your key as admin, creates the stackpaas-net Docker network, and starts the bundled stackpaas-proxy Caddy container. The data directory defaults to ~/.stackpaasd.

Note: Caddy binds host ports 80 and 443. If something else on your machine already uses them, init will fail at the proxy-start step. Free those ports first.

Run the daemon

Two options — pick whichever fits your workflow.

Foreground (development)

Runs in the current terminal so you can watch logs and Ctrl-C to stop:

stackpaasd serve

Background as a LaunchAgent (always-on)

Installs stackpaasd as a per-user launchd LaunchAgent so it survives terminal close and starts at login:

stackpaasd service install
stackpaasd service status

stackpaasd service restart bounces the agent after config changes; stackpaasd service uninstall removes it.

Configure the CLI

Point stackpaas at the local daemon. No TLS — this connects to gRPC port 9090 directly, bypassing Caddy:

stackpaas init --server localhost:9090

The CLI writes ~/.stackpaas/client.yml and uses ~/.ssh/id_ed25519 as the identity by default. Apps you deploy will still be reachable via Caddy on :80/:443 using their --domain — only the daemon control plane bypasses the proxy.

Smoke test

stackpaas list

Empty table = working. If you get an auth error, double-check that --admin-key matched the public key whose private counterpart your CLI is using.

Deploy your first app

1. Scaffold

From inside a fresh project directory:

stackpaas scaffold

Generates docker-compose.yml + .env. Add a Dockerfile next to them.

2. Get the daemon's deploy key

stackpaas deploy-key

Add this read-only key to your git host so the daemon can fetch your repo over SSH.

3. Create and deploy

stackpaas create myapp --domain myapp.localhost
git push origin main
stackpaas deploy myapp

The CLI streams deploy progress (fetch → build → compose up). Once it finishes, the app is reachable via the front proxy on the host.

Where to go next