nroxy/docs/ops/deployment.md

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 preserves clear service boundaries if separation is ever needed later.

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
• btcpay: self-hosted payment stack for crypto invoice checkout

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 to avoid an extra public webhook surface for the bot.
• Keep BTCPay persistent data and wallet material isolated from app volumes and back them up separately.
• If BTCPay requires auxiliary services, treat them as part of the payment stack rather than as app-internal services.

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 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
• provision BTCPay Server storage and wallet backup path
• create .env
• deploy Compose stack
• run database migration job
• verify web health, worker job loop, and bot polling
• verify BTCPay invoice creation, callback delivery, and payout/reconciliation procedures