StackPaaS

A lightweight, self-hosted PaaS that deploys apps from a git remote onto a Docker host via a gRPC daemon.

Architecture

StackPaaS ships as two binaries plus a bundled proxy:

• stackcube — the engineer-facing CLI. You run this on your laptop. It dials the daemon to create apps, trigger deploys, and manage authorized keys.
• stackcubed — the daemon. Runs on the host that will run your apps. Listens on gRPC port 9090, fetches commits from each app's configured git remote on demand, builds images, and brings up the app's Docker Compose stack on the shared stackcube-net network.
• stackcube-proxy — a Caddy 2 container the daemon starts at stackcubed init. Binds host ports 80 and 443, terminates TLS automatically, and reverse-proxies the daemon's domain (to :9090) and each app's domain (to its container) over the stackcube-net network.

Deploys are pull-on-demand: stackcube deploy myapp tells the daemon "deploy this app at the current commit," and the daemon fetches that commit from the app's configured git remote (e.g. GitHub) using its own deploy key. There's no push-driven hook on the daemon side.

The app contract

An app repo deployed to StackPaaS must contain:

• A compose file at the repo root: compose.yml or docker-compose.yml.
• A .env file at the repo root defining APP_PORT — the port your app listens on inside its container.
• A compose service that publishes that port via ${HOST_PORT}, which the daemon injects at deploy time.

services:
  web:
    build: .
    env_file: .env
    ports:
      - "${HOST_PORT}:${APP_PORT}"

Containers are attached to the stackcube-net Docker network so the host's front proxy can route traffic to them by container name. stackcube scaffold generates a starter compose.yml + .env for you; stackcube lint checks an existing repo against this contract before deploy.

Choose your setup

There are three ways to bring up StackPaaS depending on what you're trying to do:

Client

You're a developer connecting to a daemon someone else is running. Install stackcube only, point it at the daemon, and start deploying apps that have already been authorized for your key.

Server

You're operating the host. Install stackcubed on the Mac that will run your apps, initialize it with your SSH key as the bootstrap admin, and run it as a launchd LaunchAgent so it survives reboot and crash.

Single machine

Local-dev or solo: both binaries on one Mac. Useful for trying StackPaaS out, building app templates, or running a personal PaaS on your own hardware.