Skip to Content
LYNKORIADocs

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
ComponentRuns onDefined in
API + Socket.IODigitalOcean App Platform (sgp)infra/opentofu/platform/app.tf, image from apps/api/Dockerfile
MigrationsApp Platform pre-deploy job, same imageapp.tf (node dist/migrate.js)
LiveKit + TURNCPU-Optimized Droplet, Caddy, Redisinfra/opentofu/platform/media.tf (cloud-init)
ScannerPrivate Droplet on the VPCinfra/opentofu/platform/scanner.tf, infra/scanner/compose.yaml
PostgreSQL 18DigitalOcean Managed PostgreSQLinfra/opentofu/platform/databases.tf
ValkeyDigitalOcean Managed Valkeydatabases.tf
Object storageDigitalOcean Spaces (private bucket)infra/opentofu/platform/storage.tf
DNS, Access, Pages projectsCloudflareinfra/opentofu/platform/cloudflare.tf
Zone-wide rulesCloudflare (TLS, origin lock, cache, redirects)infra/opentofu/zone/
Console, docsCloudflare Pages (static)Built and published by .github/workflows/deploy.yml
SecretsGenerated by OpenTofu, encrypted stateinfra/opentofu/platform/secrets.tf

The architecture overview explains how these talk to each other.

How a deployment runs

  1. CI (.github/workflows/ci.yml) tests the commit, including tofu validate and a mocked tofu test.
  2. 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 runs tofu apply for 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.
  3. Infrastructure (.github/workflows/infra.yml) shows a tofu plan on every pull request that changes infra/opentofu/, and applies the shared Cloudflare zone stack on request.

Reading order

#PageYou end with
0Architecture overviewA mental model of every service and port
0PrerequisitesThe accounts, domain plan and tools you need
0Status and gapsWhat is automated, what stays manual, what is unfinished
1WorkstationTools installed, checkout validated, registry ready
2BootstrapTokens, state bucket, passphrases, Cloudflare Zero Trust (one time)
3ConfigureReviewed environments/*.tfvars (hosts, origins, LiveKit keys, sizes)
4GitHubstaging and production environments with secrets and variables
5Zone stackCloudflare TLS settings, origin-lock rules, cache and redirect rules
6First deploy (staging)Staging fully running, from one workflow run
7First sign-inAn owner console account, a project, a passing smoke test
8ProductionProduction deployed behind an approval
9OperateChanges by pull request, releases, rollback, rotation, local runs
10MonitoringMetrics, alerts and logs that reach a person
✓Production checklistEvidence 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 and api-staging.lynkoria.com, … for staging. They live in infra/opentofu/platform/environments/*.tfvars; change them there if you use another domain (and in apps/admin/public/_headers, see configure).
  • Stacks. zone is shared by both environments. platform is applied once per environment, with its own state file (lynkoria/staging.tfstate, lynkoria/production.tfstate).
  • Environment names are staging and production everywhere; resource names use staging and prod.
  • 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.

On this page