Operator-grade deployment documentation. Every guide here is annotated against the Phase 1 Implemented vs Planned matrix (docs/audits/phase1-readiness-audit.md §12) so nothing is presented as production-ready when the audit lists it as Partial, Planned, or Aspirational.
The canonical, officially-supported topology is Railway (backend) + Vercel (frontend) + Neon (Postgres). That guide lives at docs/deployment-guide.md. The hub below covers everything else: alternative topologies, cross-cutting operations, and decision support.
Status taxonomy bridge. This hub uses a five-value taxonomy (Implemented / Partial / Planned / Aspirational / Mixed). The platform-wide tags are Shipped / Beta / Planned. Mapping: Implemented = Shipped; Partial / Mixed = Beta; Planned / Aspirational = Planned. Canonical mapping lives in docs/glossary.md.
Quick start — pick a topology in 60 seconds
The canonical, officially-supported topology is Railway (backend) + Vercel (frontend) + Neon (Postgres), documented in docs/deployment-guide.md. If that doesn't fit, work through the five questions below.
- Are you self-hosting at all?
- No, I use a managed Govula tenant → nothing to deploy. See
/docs/getting-started. - Yes → continue.
- No, I use a managed Govula tenant → nothing to deploy. See
- Where MUST production data live?
- Anywhere (commercial cloud OK) → Railway + Vercel + Neon (guide).
- Customer cloud or VPC → Hybrid — backend on customer infra, frontend on Vercel (guide).
- Customer-controlled, internet-reachable → Self-hosted single VM (guide).
- Air-gapped, no outbound internet → Docker on customer infra + observability degraded (guide).
- How big is the workload?
- < 50 RPS, < 100 tenants → single backend instance is fine.
- 50–500 RPS, 100–1000 tenants → horizontal backend + pooled Postgres (scaling).
-
500 RPS — talk to us; you'll want dedicated read replicas and per-tenant rate-limit tuning.
- What's your CI/CD posture?
- What's your acceptable data loss (RPO)?
- ≤ 5 min loss is OK → Neon PITR (default).
- Zero loss for finalized writes → Neon paid + WAL streaming, OR self-hosted Postgres with synchronous replication.
- Long-term archive (audit / regulatory) → PITR + nightly logical dump (backup & recovery).
Need the full branching tree with every sub-decision and rationale? See decision-tree.md — 60 seconds, ordered branching decisions.
Topologies (one per file)
| File | Topology | Status |
|---|---|---|
../deployment-guide.md | Railway + Vercel + Neon (canonical) | Implemented — every claim audited against main |
docker.md | Local + production Docker | Implemented (compose files exist; see docker-compose*.yml) |
self-hosted.md | Single-VM and small-cluster | Partial — pattern documented; reverse-proxy examples are advisory |
hybrid.md | Frontend ↔ backend on different infra; federated cross-org | Implemented (federation) + Partial (hybrid hosting) |
Cross-cutting operations (one per file)
| File | Topic | Status |
|---|---|---|
scaling.md | Vertical / horizontal scaling, Postgres pooling, statelessness | Implemented — backend is stateless; pool config is real |
backup-recovery.md | Neon PITR, self-hosted pg_basebackup + WAL, RPO/RTO, restore drill | Implemented (Neon PITR) + Partial (self-hosted patterns) |
ci-cd.md | GitHub Actions example, secret handling, deploy gates, rollback | Partial — pattern documented; no shipped workflow file |
secrets-management.md | Env-var hierarchy, rotation, sops/Vault/Docker secrets | Implemented (env hierarchy) + Partial (rotation procedure) |
observability-setup.md | Sentry, Railway/Vercel/Neon adapters, structured-log shipping | Implemented — code paths exist with documented degradation |
production-hardening.md | CORS, JWT, rate-limit, RLS, CSP, helmet, validateEnv assertions | Implemented — every assertion enforced at boot |
decision-tree.md | "If you need X, deploy topology Y" | Implemented |
troubleshooting-matrix.md | Symptom → cause → diagnostic command → fix | Implemented — every command runs against a deployed instance |
Existing top-level operations docs
These remain canonical for the Railway+Vercel+Neon path:
docs/deployment-guide.md— official end-to-end deploydocs/production-checklist.md— pre / post-deploy gatesdocs/rollback-plan.md— runnable rollback proceduredocs/monitoring-guide.md— what to watch and when to pagedocs/ENTERPRISE-DEPLOYMENT.md— multi-tenant / single-tenant / on-prem mode flags
Audit tag legend
Every guide tags individual claims:
- Implemented — code path exists on
main, audited againstphase1-readiness-audit.md. - Partial — capability is real but bounded; gaps are called out inline.
- Planned — catalogued / scaffolded but not wired end-to-end.
- Aspirational — described as a pattern; no shipped code path.
If you find a claim in any guide here that does not match the audit matrix, file it as a documentation drift bug.
In-app version
This entire hub is mirrored at /docs/deployment inside the running app. The in-app pages link back to the markdown sources on disk, and each markdown file's front-matter in_app: field points at its rendered URL.