household-bot/docs/runbooks/coolify-compose-deploy.md

Coolify Docker Compose Deployment Plan

Goal

Deploy household-bot on a VPS that already runs Coolify, while keeping Supabase external and preserving cloud compatibility in the codebase.

Why Coolify-first

Coolify already provides:

• Git-based deployments
• domains and TLS
• environment variable management
• Docker Compose deployment support

That makes it a better target than a hand-rolled VPS deploy workflow for this project.

Deployment shape

Use a Docker Compose deployment in Coolify with three services:

• bot — Telegram webhook/API
• miniapp — static frontend container
• scheduler — periodic due-dispatch runner

Database stays external:

• Supabase / managed Postgres

Compose principles for Coolify

For Coolify Compose deployments:

• the compose file is the source of truth
• define environment variables inline with ${VAR} placeholders
• let Coolify manage domains/proxying instead of bundling Caddy/Nginx reverse proxy for the public edge
• do not rely on external env_file paths on the host

Scheduler strategy

Keep the self-hosted scheduled dispatch provider introduced in this PR.

Runtime model:

• bot handles webhook/API traffic
• scheduler calls the internal due-dispatch endpoint repeatedly
• both services share the same app image build but run different commands

Migrations

For the first Coolify version, run DB migrations from the bot startup command before the server starts.

This is intentionally pragmatic:

• no extra one-off deploy script is required
• no host SSH deploy step is required
• drizzle migrations are idempotent enough for single-service startup usage here

If the deployment setup matures later, split migrations into a dedicated release/predeploy step.

Domains

Suggested public domains:

• household-bot.whekin.dev -> bot
• household.whekin.dev -> miniapp

Coolify should manage the public routing/TLS for these services.

Required Coolify variables

Core bot/runtime:

• DATABASE_URL
• DB_SCHEMA (default public)
• TELEGRAM_BOT_TOKEN
• TELEGRAM_WEBHOOK_SECRET
• TELEGRAM_WEBHOOK_PATH
• MINI_APP_URL
• MINI_APP_ALLOWED_ORIGINS
• SCHEDULER_SHARED_SECRET
• SCHEDULED_DISPATCH_PROVIDER (self-hosted)

Optional AI/runtime:

• OPENAI_API_KEY
• PURCHASE_PARSER_MODEL
• ASSISTANT_MODEL
• TOPIC_PROCESSOR_MODEL
• assistant timeout/rate-limit variables

Miniapp:

• BOT_API_URL

Scheduler:

• SCHEDULER_POLL_INTERVAL_MS
• SCHEDULER_DUE_SCAN_LIMIT

Cloud compatibility rule

Keep these intact in the app/config layer even if Coolify becomes the main path:

• Cloud Run compatibility
• AWS compatibility
• existing cloud-specific scheduler env vars/adapters

The deployment target changes; the app should not become Coolify-only.

Recommended rollout

1. Add Coolify compose file
2. Remove VPS-specific deploy glue from this PR
3. Create a Coolify Docker Compose app from the repo
4. Fill required variables in Coolify UI
5. Assign domains to bot and miniapp
6. Deploy and verify webhook + miniapp + scheduler behavior

Notes for later

Possible future upgrades:

• add Codex/CodeRabbit review automation around PRs
• move migrations to a dedicated release step
• codify Coolify resources with Terraform/Pulumi later if that still feels worth it