How to deploy BaseBuddy to a VPS with Docker
Deploy BaseBuddy with the published Docker image, persistent app data, authorized owner setup, HTTPS, and tested backups.
Use the published image ghcr.io/stack127labs/basebuddy and the release compose.yaml to run BaseBuddy on your VPS. The image works on linux/amd64 and linux/arm64 servers. The app runs as user 10001 and connects to your existing Postgres or Supabase content database.
Configure your server
Download the release files and keep .env private:
shmkdir basebuddy && cd basebuddy
curl -fsSLO https://raw.githubusercontent.com/stack127labs/basebuddy/v0.2.2/compose.yaml
curl -fsSL -o .env https://raw.githubusercontent.com/stack127labs/basebuddy/v0.2.2/.env.example
chmod 600 .envFor the optional Caddy HTTPS setup, clone the repository at the release tag instead (git clone --branch v0.2.2 https://github.com/stack127labs/basebuddy.git), then copy .env.example to .env. Set the auth secret and content database connection in environment variables. For browser setup, set BASEBUDDY_SETUP_TOKEN to at least 32 random characters. Enter the same value in the account step on /onboarding.
Create the first owner before opening public access, or require the setup token. CLI owner creation does not require a setup token.
Start
shdocker compose pull
docker compose up -dThe app listens on 127.0.0.1:8080 by default. Open /onboarding through a private connection or an SSH tunnel. The named volume preserves /app/basebuddy-data when you replace a container. Do not remove that volume during an upgrade.
For Supabase/Postgres app data, prepare basebuddy.app_state and basebuddy.audit_events with docker compose run --rm basebuddy pnpm basebuddy app-data:migrate before creating the owner. If the runtime role cannot create tables, apply app-data:sql as an administrator. Normal runtime access needs read/write grants and does not run schema creation.
Put the app behind HTTPS
Use your existing HTTPS proxy, or set BASEBUDDY_DOMAIN and use the included Caddy override:
shdocker compose -f compose.yaml -f compose.https.yaml up -dPoint the domain at your VPS and keep ports 80 and 443 available for Caddy. It forwards traffic to the app and persists its certificates.
Verify
shdocker compose exec basebuddy pnpm basebuddy doctor --json
docker compose exec basebuddy pnpm setup:check/api/health checks the running process. /api/ready checks setup and database reachability, returning 503 until the install is ready. Check sign-in, project listing, and a saved mapping. Replace the container and confirm the same account and mapping remain available.
Back up app data and test a restore into a separate private install before production upgrades. To upgrade, change the image tag in compose.yaml, then run docker compose pull and docker compose up -d. Keep the prior tag written down for rollback. Operations explains the backup scope and checks.
Run one app instance. Shared database app data does not distribute editor presence, caches, or request limits. Production images must not use Playwright builds or test environment files.