Initial import

docs/ops/deployment.md

@@ -0,0 +1,48 @@
+# Deployment Plan
+
+## Chosen target
+Deploy on one VPS with Docker Compose.
+
+## Why this target
+- The system has multiple long-lived components: web, worker, bot, database, and reverse proxy.
+- Compose gives predictable service boundaries, easier upgrades, and easier recovery than manually managed host processes.
+- It keeps the path open for later separation of web, worker, and bot without reworking the repository layout.
+
+## Expected services
+- `migrate`: one-shot schema bootstrap job run before app services start
+- `web`: Next.js app serving the site, dashboard, admin UI, and API routes
+- `worker`: background job processor
+- `bot`: Telegram admin bot runtime
+- `postgres`: primary database
+- `caddy`: TLS termination and reverse proxy
+- optional `minio`: self-hosted object storage for single-server deployments
+
+## Deployment notes
+- Run one Compose project on a single server.
+- Keep persistent data in named volumes or external storage.
+- Keep secrets in server-side environment files or a secret manager.
+- Back up PostgreSQL and object storage separately.
+- Prefer Telegram long polling in MVP to avoid an extra public webhook surface for the bot.
+
+## Upgrade strategy
+- Build new images.
+- Run the one-shot database schema job.
+- Restart `web`, `worker`, and `bot` in the same Compose project.
+- Roll back by redeploying the previous image set if schema changes are backward compatible.
+
+## Current database bootstrap state
+- The current Compose template runs a `migrate` service before `web`, `worker`, and `bot`.
+- The job runs `prisma migrate deploy` from the committed migration history.
+- The same bootstrap job also ensures the default MVP `SubscriptionPlan` row exists after migrations.
+- Schema changes must land with a new committed Prisma migration before deployment.
+
+## Initial operational checklist
+- provision VPS
+- install Docker and Compose plugin
+- provision DNS and TLS
+- provision PostgreSQL storage
+- provision S3-compatible storage or enable local MinIO
+- create `.env`
+- deploy Compose stack
+- run database migration job
+- verify web health, worker job loop, and bot polling