Self-host with Docker Compose

• A server with DockerDocker and the Compose plugin. The stack runs six containers.
• A TLS reverse proxyCaddy, Traefik, nginx: anything that terminates TLS and forwards to the two ports below.
• A domain you controlA hostname for the web app. The api gets a second hostname under the same registrable domain, or a path on the web app’s host. The session cookie cannot cross to another domain.

This page uses api.example.com for the api and app.example.com for the web app.

git clone https://github.com/croffasia/itsaplan.git
cd itsaplan
cp .env.example .env
docker compose up -d

Fill in the seven values below in .env before the last command. That starts the whole stack: Postgres, RustFS, api, worker, bot and web. The four services run the images published on each release, so nothing is built.

On a machine with Bun, the setup script generates the secrets for you. Run bun install && bun run setup, answer Generate env, and answer no when it offers to write the files: it prints .env and apps/web/.env for you to copy onto the server.

The stack refuses to start while one of these is missing:

• API_URLPublic origin of the api. Example: https://api.example.com.
• APP_URLPublic origin of the web app. Example: https://app.example.com.
• POSTGRES_PASSWORDopenssl rand -base64 32
• BETTER_AUTH_SECRETopenssl rand -base64 32
• APP_ENCRYPTION_KEYopenssl rand -base64 32. It encrypts the provider keys stored in the database. Change it later and those become unreadable.
• S3_ACCESS_KEY_IDThe RustFS root user. Any name over three characters.
• S3_SECRET_ACCESS_KEYopenssl rand -base64 32. At least eight characters.

DATABASE_URL and S3_ENDPOINT are set by the compose file. VERSION pins one release instead of the newest.

Everything optional is documented in .env.example: legal document URLs, passkey and cookie settings, the outbound request policy, telemetry opt-out and worker tuning. Mail, AI provider keys, single sign-on and the Telegram bot token are not variables. You configure them in the interface after you sign in.

Terminate TLS at your proxy and forward each hostname to its container port:

• api.example.comthe api, port 3000
• app.example.comthe web app, port 3001

Both origins must be https and must match API_URL and APP_URL exactly. Passkeys bind to the web hostname taken from APP_URL. On a multi-label TLD, a deep subdomain, or an APP_URL on the apex domain, set COOKIE_DOMAIN as well, for example .example.com.

The api can also live on a path of the web host, with API_URL=https://app.example.com/api. The proxy then sends /api/* to port 3000 with the prefix removed, and everything else to port 3001. For MCP clients that sign in with OAuth, it also sends /.well-known/oauth-authorization-server*, /.well-known/oauth-protected-resource* and /.well-known/openid-configuration* to the api. No second hostname or certificate is needed.

The one-shot migrate service applies the migrations before the api starts, so there is no database step. Open APP_URL and register. The first account becomes the instance admin, and admin settings open from there: mail provider, AI providers, single sign-on, the Telegram bot token, and who may register.

git pull
docker compose pull
docker compose up -d

git pull updates the compose file; the services come from the registry. Changing API_URL or APP_URL afterwards needs only docker compose up -d.

The migrate service applies the migrations on every docker compose up -d, and api, worker and bot start only after it succeeds. Before it applies anything, it dumps the database into the db-backups volume and fails if that dump fails. Dumps are deleted after 30 days; BACKUP_RETENTION_DAYS changes the window, and SKIP_PRE_MIGRATION_BACKUP=1 upgrades without one. After the upgrade the app shows the instance owner where the dump is and what the migrations changed.

If you call the API from your own scripts or from an MCP client, read the release notes for the paths a release removed.

docker compose up -d --build

That builds every service from the checkout and runs those images. Nothing else changes, and the same command picks up local edits.

For anything else, read the logs: docker compose logs -f api, and the same for migrate, web, worker and bot.

• BugsReport them in GitHub issues.
• Questions and setup helpAsk in GitHub discussions.
• This guideIt ships with the source as docs/self-hosting.md, which also covers single sign-on and SCIM provisioning.

Other ways to run it: Railway, Coolify, Kubernetes.