Operator guide

How ProjectStart runs on one host as three Docker containers (deploy/prod/compose.yaml), behind the host’s Caddy. Steps marked Not verified on dev. have not been run on the dev site yet. Pending: marks an open point in the code that affects a step.

• Install: from an empty Ubuntu host with LXD and Caddy to a running site and its first administrator.
• Upgrade: moving to new images in order, and what a restart ends.
• Way back: going back to the previous images, and when the database allows it.
• Backup and restore: what to keep, consistent SQLite copies, and restore.
• Reverse proxy: the web’s socket and the host Caddyfile.

How it runs

• An unprivileged web process (the admin site), an unprivileged worker that carries out operations, and a narrowly scoped root controller, the only part that touches LXD and Caddy.
• In production the three run as Docker containers on one Ubuntu host, behind the host’s Caddy.
• Project containers are LXD system containers; Caddy routes each project’s domain to port 3000 of its container.
• Remote projects run on servers you already have, reached over SSH or through a small daemon installed there.

Requirements

• An Ubuntu host (tested on Ubuntu 26.04) with Docker and Compose, LXD from the snap, Caddy and sqlite3.
• A domain for the admin site and a base domain for project sites, with DNS pointing at the host.
• Optionally an approved Git host for project repositories, and Claude or Codex sign-ins for the agents.