Deployment
The deployment handbook for self-hosting Lynkoria on DigitalOcean Singapore with Cloudflare, built and updated by OpenTofu and GitHub Actions.
Who this section is for
Operators who run Lynkoria. You need basic Linux, DNS, Git and GitHub knowledge. If you are integrating Lynkoria into a product, start with the developer guides.
Lynkoria's infrastructure is code. OpenTofu describes every DigitalOcean and Cloudflare resource in infra/opentofu/, and GitHub Actions applies it. After a one-time bootstrap (accounts, tokens, a state bucket), a deployment is a merge to main for staging and an approved workflow run for production. Nobody creates servers, databases, DNS records or secrets by hand.
What gets deployed
flowchart LR
subgraph Internet
U[Browsers and apps]
PB[Product backends]
OP[Operators]
end
subgraph Cloudflare
CFAPI[api.lynkoria.com<br/>proxy + origin lock]
PAGES1[console.lynkoria.com<br/>Pages + Access]
PAGES2[lynkoria.com<br/>Pages docs]
end
subgraph DO[DigitalOcean SGP1 VPC]
API[App Platform: API<br/>REST, Socket.IO, workers]
MIG[Pre-deploy job: migrations]
LK[Media Droplet<br/>Caddy + LiveKit + TURN + Redis]
SC[Scanner Droplet<br/>scanner + ClamAV]
PG[(Managed PostgreSQL)]
VK[(Managed Valkey)]
end
SP[(Spaces bucket)]
U --> CFAPI --> API
PB --> CFAPI
OP --> PAGES1 --> CFAPI
U --> PAGES2
U -- WSS / UDP / TURN, DNS only --> LK
API --> PG
MIG --> PG
API --> VK
API -- private TLS :3344 --> SC
API --> LK
LK -- webhooks --> CFAPI
API --> SP
U -- presigned URLs --> SP
| Component | Runs on | Defined in |
|---|---|---|
| API + Socket.IO | DigitalOcean App Platform (sgp) | infra/opentofu/platform/app.tf, image from apps/api/Dockerfile |
| Migrations | App Platform pre-deploy job, same image | app.tf (node dist/migrate.js) |
| LiveKit + TURN | CPU-Optimized Droplet, Caddy, Redis | infra/opentofu/platform/media.tf (cloud-init) |
| Scanner | Private Droplet on the VPC | infra/opentofu/platform/scanner.tf, infra/scanner/compose.yaml |
| PostgreSQL 18 | DigitalOcean Managed PostgreSQL | infra/opentofu/platform/databases.tf |
| Valkey | DigitalOcean Managed Valkey | databases.tf |
| Object storage | DigitalOcean Spaces (private bucket) | infra/opentofu/platform/storage.tf |
| DNS, Access, Pages projects | Cloudflare | infra/opentofu/platform/cloudflare.tf |
| Zone-wide rules | Cloudflare (TLS, origin lock, cache, redirects) | infra/opentofu/zone/ |
| Console, docs | Cloudflare Pages (static) | Built and published by .github/workflows/deploy.yml |
| Secrets | Generated by OpenTofu, encrypted state | infra/opentofu/platform/secrets.tf |
The architecture overview explains how these talk to each other.
How a deployment runs
- CI (
.github/workflows/ci.yml) tests the commit, includingtofu validateand a mockedtofu test. - Deploy (
.github/workflows/deploy.yml) builds and scans the API image (and the scanner image when its sources changed), pushes them to your container registry, then runstofu applyfor the environment. App Platform runs migrations before switching traffic. The workflow smoke-tests the API and the origin lock, then publishes the console and docs to Pages. - Infrastructure (
.github/workflows/infra.yml) shows atofu planon every pull request that changesinfra/opentofu/, and applies the shared Cloudflarezonestack on request.
Reading order
| # | Page | You end with |
|---|---|---|
| 0 | Architecture overview | A mental model of every service and port |
| 0 | Prerequisites | The accounts, domain plan and tools you need |
| 0 | Status and gaps | What is automated, what stays manual, what is unfinished |
| 1 | Workstation | Tools installed, checkout validated, registry ready |
| 2 | Bootstrap | Tokens, state bucket, passphrases, Cloudflare Zero Trust (one time) |
| 3 | Configure | Reviewed environments/*.tfvars (hosts, origins, LiveKit keys, sizes) |
| 4 | GitHub | staging and production environments with secrets and variables |
| 5 | Zone stack | Cloudflare TLS settings, origin-lock rules, cache and redirect rules |
| 6 | First deploy (staging) | Staging fully running, from one workflow run |
| 7 | First sign-in | An owner console account, a project, a passing smoke test |
| 8 | Production | Production deployed behind an approval |
| 9 | Operate | Changes by pull request, releases, rollback, rotation, local runs |
| 10 | Monitoring | Metrics, alerts and logs that reach a person |
| ✓ | Production checklist | Evidence that the platform works end to end |
Prefer to run everything from your own terminal first? Manual deployment walks through the same stacks by hand: prerequisites, the docs and console sites, then the realtime platform.
Reference: environment variables, Cloudflare zone, troubleshooting, production recommendations, operations and upgrades.
Conventions in this handbook
- Hostnames are the repository's:
api.lynkoria.com,rtc.lynkoria.com, … for production andapi-staging.lynkoria.com, … for staging. They live ininfra/opentofu/platform/environments/*.tfvars; change them there if you use another domain (and inapps/admin/public/_headers, see configure). - Stacks.
zoneis shared by both environments.platformis applied once per environment, with its own state file (lynkoria/staging.tfstate,lynkoria/production.tfstate). - Environment names are
stagingandproductioneverywhere; resource names usestagingandprod. - Placeholders look like
YOUR_…. Replace every one.
A first tofu apply creates two managed database clusters, two Droplets and an App Platform app. Expect 20–40 minutes, most of it waiting for DigitalOcean. Later deploys only change what changed.
Accuracy statement
The OpenTofu code is checked with tofu validate and a tofu test that plans the platform stack against mocked providers (infra/opentofu/platform/tests/). Resource arguments were checked against the provider schemas (digitalocean/digitalocean 2.107, cloudflare/cloudflare 5.29). The stacks have not yet been applied to real accounts; the first real apply is the remaining verification. See blockers.