Get started: Server

Set up the stackcubed daemon on a host you own so engineers can deploy apps to it.

This guide is for the operator of the StackPaaS host. Once it's running, your team members follow Get started: Client to connect.

Requirements

• An Apple Silicon Mac that will host the daemon
• Docker — Colima is recommended (lightweight, MIT licensed); Docker Desktop also works
• A domain pointed at the host (for example paas.example.com) — used by the bundled Caddy proxy to obtain a TLS certificate
• Host ports 80 and 443 free — the bundled Caddy proxy binds them at init time
• An SSH public key — this becomes the bootstrap admin for the daemon

What gets installed

Three runtime pieces end up on this host:

• stackcubed — the gRPC daemon (port 9090, internal).
• stackcube-proxy — a Caddy 2 container started by stackcubed init. Binds host 80 and 443, terminates TLS automatically, and reverse-proxies the daemon domain to :9090 and each app domain to its container.
• A stackcube-net Docker network — created by stackcubed init; every app container and the proxy attach to it.

Install

Homebrew

brew tap stackcube/tap
brew install stackcubed

Install stackcube as well if you want to manage the daemon (add keys, list apps) from this same machine. If admin commands will run from a separate laptop, leave it off.

Initialize the daemon

One command bootstraps the whole host. It detects your Docker setup, writes ~/.stackcubed/config.yml, generates the daemon's deploy key pair, registers your SSH public key as the bootstrap admin, creates the stackcube-net Docker network, generates a Caddyfile from the configured domain, and starts the stackcube-proxy container:

stackcubed init \
  --admin-key ~/.ssh/id_ed25519.pub \
  --domain paas.example.com

The data directory defaults to ~/.stackcubed. Override with --data-dir if you need a different location. After init, the command prints the daemon's deploy public key — note it down; you'll add it to git hosts later (stackcube deploy-key can also retrieve it).

Engineers will then connect to paas.example.com:443 with TLS — Caddy obtains the certificate automatically (Let's Encrypt by default) and reverse-proxies through to the daemon.

Run the daemon as a LaunchAgent

Install stackcubed as a launchd LaunchAgent so it survives SSH logout, restarts on crash, and auto-starts at login:

stackcubed service install

This copies the binary into ~/.stackcubed/bin/stackcubed, installs a plist pointing at it, and starts the agent. Subsequent self-updates rewrite that same canonical binary path. Verify it's running:

stackcubed service status

You can stackcubed service restart after config changes, or stackcubed service uninstall to remove the agent entirely.

Authorize your engineers

You're the only authorized key right now (the bootstrap admin). To let other people use this daemon, register their SSH public keys via the CLI. From a client (this same machine if you installed both binaries; otherwise a laptop pointing at this daemon):

stackcube keys add alice --key "ssh-ed25519 AAAA..." --role developer
stackcube keys add bob   --key "ssh-ed25519 AAAA..." --role admin

Roles: admin (can manage keys and apps) or developer (can deploy apps but not change keys). Each engineer then runs the client setup with their key.

Hook up your git host

Apps deploy from a git remote that the daemon fetches over SSH. Register the daemon's deploy public key as a read-only deploy key on each app's git host:

stackcube deploy-key

The same key works for every app on this daemon — add it once per repository (or as a user-level key in your git host if your provider supports that).

Where to go next

• Configuration — tune ~/.stackcubed/config.yml (port, network name, port allocation range, Compose command).
• CLI reference — full stackcubed command surface, including the service subcommands.
• Get started: Client — pass this on to engineers connecting to the daemon.