Manual deployment with OpenTofu
Deploy Lynkoria to production from your own machine with the repository's OpenTofu stacks, step by step — prerequisites, the docs and console sites first, then the realtime platform.
This page deploys everything from your own terminal, with the same OpenTofu code GitHub Actions uses. Use it for the first deployment, to learn what the automation does, or when CI is not set up yet. Once it works, you can hand over to the Deploy workflow; both use the same state, so nothing is lost.
The order is:
- Prerequisites — accounts, tools, tokens, state bucket (once).
- Your shell — one private file with every value OpenTofu needs.
- Zone stack — Cloudflare settings shared by all environments.
- Sites — docs and admin console live on Cloudflare Pages.
- Realtime platform — API, LiveKit, scanner, databases, storage.
- First sign-in and checks.
- Optional: staging — a second, separate environment for testing changes.
The page deploys production (api.lynkoria.com, console.lynkoria.com, lynkoria.com). Commands run from the repository root in bash or zsh (on Windows, inside WSL).
This code has not been applied to real accounts yet
The stacks pass tofu validate and a mocked plan test, but this will be their first real apply. Read every plan before you type yes. Mistakes on the first run are easy to fix by applying again, but the database, the attachments bucket and the pepper are protected from deletion, and recreating the media Droplet many times in a week can hit Let's Encrypt's certificate limit for rtc and turn. If you want a rehearsal first, do Part 7 before Parts 4–6.
Part 1: Prerequisites
1.1 Accounts
| Account | Needed for |
|---|---|
| DigitalOcean, with billing | App Platform, Droplets, databases, Spaces, registry |
Cloudflare, with lynkoria.com active as a zone | DNS, TLS, Access, Pages |
| Cloudflare Zero Trust (free plan), recommended | Access login (with MFA) in front of the console; see 1.6 |
| GitHub (optional for this page) | Only when you hand over to CI later |
If your DigitalOcean account cannot create dedicated-CPU Droplets (c-4), request a limit increase first (Settings → Team → Droplet limit or a support ticket).
1.2 Tools
sudo apt-get update
sudo apt-get install -y git jq curl openssl postgresql-client unzipThen install, from their official pages:
| Tool | Why | Check |
|---|---|---|
| OpenTofu | Runs the stacks. Use the version in infra/opentofu/.opentofu-version (install) | tofu version |
| doctl | DigitalOcean CLI, also used by the database-grants step (install) | doctl version |
| AWS CLI v2 | Creates the state bucket (install) | aws --version |
| Docker with Buildx | Builds the API and scanner images | docker buildx version |
| Node 26 + pnpm 12.18.0 | Builds the console and docs | node --version, pnpm --version |
Get the code and check it:
git clone YOUR_REPOSITORY_URL lynkoria && cd lynkoria
pnpm install --frozen-lockfile
pnpm infra:tofupnpm infra:tofu must end with 1 passed, 0 failed.
1.3 DigitalOcean token and registry
- Control panel → API → Tokens → Generate New Token, full access, with an expiry. Copy it.
- Log in and check the registry:
doctl auth init
doctl registry getIf a registry is listed, use it; its plan must allow two more repositories (Basic or higher, Container Registry → Settings). If none exists: doctl registry create YOUR_REGISTRY --region sgp1 --subscription-tier basic.
1.4 Spaces key and the state bucket
- Control panel → Spaces Object Storage → Access Keys → Create Access Key → Full access. Copy the key ID and secret.
- Create the bucket that stores OpenTofu's state (once, shared by all environments):
aws configure --profile do-spaces # key ID, secret, region sgp1
s3() { aws --profile do-spaces --endpoint-url https://sgp1.digitaloceanspaces.com "$@"; } # works in bash and zsh
s3 s3api create-bucket --bucket YOUR_STATE_BUCKET
s3 s3api put-bucket-versioning --bucket YOUR_STATE_BUCKET --versioning-configuration Status=EnabledPick a unique name such as lynkoria-tofu-state-x1y2.
1.5 State passphrases
OpenTofu encrypts its state. Generate two passphrases (a third only if you add staging later) and keep them in your password manager:
openssl rand -base64 33 # zone passphrase
openssl rand -base64 33 # production passphraseWithout its passphrase OpenTofu cannot read the state, and every generated secret in it (database passwords, signing keys, the scanner CA) is lost.
1.6 Cloudflare
-
On the zone's Overview page, copy the Zone ID and Account ID.
-
Decide whether to use Cloudflare Access (Zero Trust) in front of the console and the admin API:
Access on (default, recommended) Access off ( TF_VAR_enable_access=false)Who can see the console login page Only the emails you list Anyone on the internet Multi-factor authentication Yes, through your Access login method No: the console has passwords only Brute-force protection Blocked at Cloudflare before reaching the API The API's lockout (5 attempts) and rate limits Cost and setup Free up to 50 users; create a Zero Trust team once None Without Access, one leaked operator password controls every project and key, so use it unless you are a solo operator with a unique password in a password manager. You can switch later with one apply.
If Access is on: open Zero Trust once and choose a team name. The team domain is
YOUR_TEAM.cloudflareaccess.com. Under Settings → Authentication, add a login method (Google, GitHub, one-time PIN, …). -
My Profile → API Tokens → Create Token → Create Custom Token (custom token, not a template), with these permissions:
Scope Permission (as shown in the token form) Level Used for Account Cloudflare Pages Edit Pages projects and custom domains; wrangler pages deployAccount Access: Apps and Policies Edit The console's Access application and policy (only with Access on) Zone DNS Edit All DNS records Zone Zone Settings Edit TLS mode, Always Use HTTPS, WebSockets, … Zone Transform Rules Edit Origin-lock header rule Zone Cache Rules Edit API cache bypass Zone Single Redirect Edit www→ apex redirectSet Account Resources to your account and Zone Resources to
lynkoria.com.Can't find "Cloudflare Pages"? Cloudflare now shows Pages inside Workers & Pages in the dashboard, but the token permission is still named Cloudflare Pages (Cloudflare's permission list). In the Account row's permission dropdown, type
Pagesto filter. Do not pick Workers Scripts instead: it covers Workers, not Pages projects. If the option really isn't there, start from the Edit Cloudflare Workers template, check that its list includes Cloudflare Pages: Edit, and add the Access and zone permissions above.Copy the token when it is shown; Cloudflare shows it only once.
1.7 SSH key and your IP
doctl compute ssh-key import lynkoria-operator --public-key-file ~/.ssh/id_ed25519.pub
doctl compute ssh-key list --format Name,FingerPrint
curl -s https://api.ipify.org; echoNote the fingerprint and your IP.
1.8 Review the environment settings
Open infra/opentofu/platform/environments/production.tfvars. Check the hostnames, and replace the examples: set allowed_origins to your real product web apps (exact https:// origins) and livekit_key_refs to one entry per product (for example ["vibelynk:production"]). Commit the change, so the repository matches what you deploy. See configure for every setting.
Part 2: Prepare your shell
Put every value in one private file outside the repository:
mkdir -m 700 -p ~/lynkoria-secure
touch ~/lynkoria-secure/production.env && chmod 600 ~/lynkoria-secure/production.env
"${EDITOR:-nano}" ~/lynkoria-secure/production.envContents (replace every YOUR_…; lists are JSON):
# Credentials
DIGITALOCEAN_ACCESS_TOKEN=YOUR_DO_TOKEN
SPACES_ACCESS_KEY_ID=YOUR_SPACES_KEY_ID
SPACES_SECRET_ACCESS_KEY=YOUR_SPACES_SECRET
CLOUDFLARE_API_TOKEN=YOUR_CLOUDFLARE_TOKEN
TOFU_STATE_BUCKET=YOUR_STATE_BUCKET
ZONE_PASSPHRASE=YOUR_ZONE_PASSPHRASE
ENV_PASSPHRASE=YOUR_PRODUCTION_PASSPHRASE
# Account-specific settings
TF_VAR_cloudflare_account_id=YOUR_ACCOUNT_ID
TF_VAR_cloudflare_zone_id=YOUR_ZONE_ID
TF_VAR_owner_email=you@example.com
# Cloudflare Access (1.6). With Access on, set both lines below; the owner email must be in the list.
TF_VAR_cf_access_team_domain=YOUR_TEAM.cloudflareaccess.com
TF_VAR_access_allowed_emails='["you@example.com"]'
# With Access off, delete the two lines above and uncomment this one:
# TF_VAR_enable_access=false
TF_VAR_docr_registry=YOUR_REGISTRY
TF_VAR_ssh_key_fingerprints='["YOUR_FINGERPRINT"]'
TF_VAR_admin_ips='["YOUR_IP/32"]'Load it in every new terminal before running the commands below:
set -a; source ~/lynkoria-secure/production.env; set +a
export TF_VAR_state_passphrase="$ENV_PASSPHRASE" TF_VAR_zone_state_passphrase="$ZONE_PASSPHRASE"doctl reads DIGITALOCEAN_ACCESS_TOKEN from the environment, so it uses the same token without saving it.
infra/opentofu/run.sh is the only command you use to run OpenTofu. It picks the right state file and settings: run.sh zone … for the shared Cloudflare stack, run.sh production … for production.
Part 3: The shared Cloudflare zone stack
This sets Full (strict) TLS, WebSockets, the origin-lock header rule for each API host, the API cache bypass, the www redirect, DMARC and CAA. It is shared by all environments, so it runs once even if you add staging later.
TF_VAR_state_passphrase="$ZONE_PASSPHRASE" infra/opentofu/run.sh zone plan
TF_VAR_state_passphrase="$ZONE_PASSPHRASE" infra/opentofu/run.sh zone applyThe zone commands override TF_VAR_state_passphrase with the zone passphrase for that one command. Read the plan, then type yes at the apply prompt. If it fails because a ruleset "already exists", the zone has rules made in the dashboard; delete them or import them.
Check: Cloudflare dashboard → SSL/TLS shows Full (strict); Rules lists the origin-lock, cache and redirect rules.
Part 4: The sites (docs and console)
The sites are static. You create their Cloudflare Pages projects, domains and (with Access on) the Access login with a targeted apply, then build and upload them. The API does not have to exist yet: the console is built with the API's hostname, which is fixed.
4.1 Create the Pages projects, domains and Access login
The platform stack always needs two image digests, but none of the resources below uses them, so pass a placeholder:
ZERO="sha256:$(printf '0%.0s' {1..64})"
SITES=(-target=cloudflare_pages_project.site -target=cloudflare_pages_domain.site -target=cloudflare_dns_record.site \
-target=cloudflare_zero_trust_access_policy.operators -target=cloudflare_zero_trust_access_application.admin)
infra/opentofu/run.sh production plan "${SITES[@]}" -var "api_image_digest=$ZERO" -var "scanner_image_digest=$ZERO"
infra/opentofu/run.sh production apply "${SITES[@]}" -var "api_image_digest=$ZERO" -var "scanner_image_digest=$ZERO"OpenTofu warns that -target is for exceptional use; that is expected here. It creates the projects lynkoria-console-prod and lynkoria-docs-prod, the custom domains console.lynkoria.com and lynkoria.com (the apex), their DNS records, and the Access application that guards the console. With Access off, the two Access targets simply create nothing.
4.2 Build
VITE_API_ORIGIN=https://api.lynkoria.com \
VITE_DOCS_URL=https://lynkoria.com/docs \
NEXT_PUBLIC_SITE_URL=https://lynkoria.com \
pnpm --filter @lynkoria/admin... --filter @lynkoria/docs... build
node scripts/check-bundle-secrets.mjsThe last command fails if anything secret-looking ended up in the built files.
4.3 Upload
export CLOUDFLARE_ACCOUNT_ID="$TF_VAR_cloudflare_account_id"
npx --yes wrangler@4.161.0 pages deploy apps/admin/dist --project-name lynkoria-console-prod --branch production
npx --yes wrangler@4.161.0 pages deploy apps/docs/out --project-name lynkoria-docs-prod --branch production--branch production matches the projects' production branch, so the upload is served on the custom domains.
4.4 Check
curl -sI https://lynkoria.com/docs/ | head -1
curl -sI https://console.lynkoria.com | grep -iE 'content-security-policy|strict-transport'The docs load. With Access on, the console shows the Cloudflare Access login first; after it (or straight away with Access off) the console's sign-in page appears, but signing in only works once the API exists (Part 5). New custom domains can take a few minutes to get certificates.
Part 5: The realtime platform
5.1 Build and push the images
doctl registry login --expiry-seconds 3600
REG="registry.digitalocean.com/$TF_VAR_docr_registry"
SHA=$(git rev-parse HEAD)
docker buildx build --platform linux/amd64 -f apps/api/Dockerfile \
-t "$REG/lynkoria-api:$SHA" --push --metadata-file /tmp/api-image.json .
docker buildx build --platform linux/amd64 -f apps/scanner/Dockerfile \
-t "$REG/lynkoria-scanner:$SHA" --push --metadata-file /tmp/scanner-image.json .
API_DIGEST=$(jq -r '."containerimage.digest"' /tmp/api-image.json)
SCANNER_DIGEST=$(jq -r '."containerimage.digest"' /tmp/scanner-image.json)
echo "$API_DIGEST $SCANNER_DIGEST"Both must print sha256:…. The first build takes a while.
5.2 First apply, with the API record not proxied yet
App Platform must check the API hostname and issue its certificate before Cloudflare proxies it, so the first apply keeps the record DNS only:
export TF_VAR_api_dns_proxied=false
infra/opentofu/run.sh production plan -var "api_image_digest=$API_DIGEST" -var "scanner_image_digest=$SCANNER_DIGEST"
infra/opentofu/run.sh production apply -var "api_image_digest=$API_DIGEST" -var "scanner_image_digest=$SCANNER_DIGEST"The plan lists about 50 resources to create. The apply takes 20–40 minutes, mostly waiting for the databases. In order, it creates:
- Generated secrets (pepper, webhook master, LiveKit keys, messaging key, scanner token, scanner CA and certificate).
- The VPC, PostgreSQL (database, two roles, pool) and Valkey.
- Database grants: a script briefly allows your IP on the database, applies the grants with
psql, and removes the rule. - The Spaces bucket (CORS, lifecycle) and the API's bucket key.
- The media Droplet (LiveKit, Caddy, Redis) with its firewall and
rtc/turnrecords. - The scanner Droplet with its firewall and private DNS record.
- The App Platform app: migrations first, then the API, then the owner-role job.
- The
apirecord.
If it stops with an error, fix the cause (troubleshooting) and run the same apply again; it continues where it stopped.
5.3 Wait for the API domain, then turn on the proxy
DigitalOcean control panel → Apps → lynkoria-api-prod → Settings → Domains: wait until api.lynkoria.com is Active. Then:
unset TF_VAR_api_dns_proxied
infra/opentofu/run.sh production apply -var "api_image_digest=$API_DIGEST" -var "scanner_image_digest=$SCANNER_DIGEST"The plan should change only the api record (proxied). From now on the API only accepts traffic through Cloudflare.
5.4 Check
infra/opentofu/run.sh production output
curl -sf https://api.lynkoria.com/health/ready && echo
curl -sI https://api.lynkoria.com/health/ready | grep -i cf-ray
curl -s -o /dev/null -w '%{http_code}\n' "$(infra/opentofu/run.sh production output -raw app_default_ingress)/openapi.json"
curl -sI https://rtc.lynkoria.com | head -1Expected: readiness OK, a cf-ray header, 403 from the direct App Platform address (the origin lock), and an HTTP answer from rtc (its certificate can take a few minutes). To look inside the Droplets, use the IPs from output:
ssh root@MEDIA_PUBLIC_IP 'cloud-init status --long; cd /opt/livekit && docker compose ps'
ssh root@SCANNER_PUBLIC_IP 'docker compose -f /opt/lynkoria-scanner/compose.yaml ps'The scanner turns healthy after ClamAV's first signature download (several minutes).
Run one more plan; it should report No changes. If it keeps proposing changes nobody made, note them; see status and gaps.
Part 6: First sign-in and checks
The owner-role job already gave TF_VAR_owner_email the owner role. Create its password (interactive on purpose):
doctl apps console "$(infra/opentofu/run.sh production output -raw app_id)" apiInside the container:
node dist/admin-users.js create --email you@example.com --role owner
exitThen:
- With Access on: open
https://api.lynkoria.com/v1/admin/meonce (logs you in to Access for the API host). Skip this with Access off. - Open
https://console.lynkoria.comand sign in. - Create a project, a
productionenvironment with a LiveKit key reference fromlivekit_key_refs, and a key (projects and keys). - Run the smoke test with a short-lived key, as in step 7.4, with
PUBLIC_API_ORIGIN=https://api.lynkoria.com. Revoke the key afterwards. - Work through the production checklist and the security checklist before real traffic.
Part 7: Optional: a staging environment
Staging is a second, completely separate copy of the platform (own state, databases, Droplets, secrets and hostnames: api-staging.lynkoria.com, console-staging.lynkoria.com, staging.lynkoria.com, rtc-staging…). It costs a second set of resources, and gives you somewhere to try upgrades, such as a LiveKit version change that replaces the media Droplet, before production. You can add it now (before Parts 4–6, as a rehearsal) or at any time later without touching production.
- Generate a staging passphrase (
openssl rand -base64 33). cp ~/lynkoria-secure/production.env ~/lynkoria-secure/staging.envand setENV_PASSPHRASEto the staging passphrase. KeepZONE_PASSPHRASEthe same. Use separate tokens if you want stronger separation.- Review
infra/opentofu/platform/environments/staging.tfvars(origins,livekit_key_refssuch as["vibelynk:staging"]). - Load the staging file instead of the production one (Part 2) and repeat Parts 4–6 with these changes:
| In Parts 4–6 | Production | Staging |
|---|---|---|
run.sh stack | production | staging |
| Pages projects | lynkoria-console-prod, lynkoria-docs-prod | lynkoria-console-staging, lynkoria-docs-staging |
Wrangler --branch | production | staging |
| Site build URLs | https://api.lynkoria.com, https://lynkoria.com | https://api-staging.lynkoria.com, https://staging.lynkoria.com |
| App Platform app | lynkoria-api-prod | lynkoria-api-staging |
| Hostnames to check | api., console., rtc., turn.lynkoria.com | api-staging., console-staging., rtc-staging., turn-staging.lynkoria.com |
The zone stack (Part 3) is already applied; skip it. The console's security headers already allow both API hosts.
Updating later
- New code: repeat 5.1 (build images), then the apply from 5.3 with the new digests. If you have staging, deploy there first. For site changes, repeat 4.2–4.3.
- Infrastructure change: edit
infra/opentofu/, runpnpm infra:tofu, thenplanandapplyas in 5.3. - Hand over to CI: fill in the GitHub environments (step 4); the Deploy workflow then does 4.2–4.3 and 5.1–5.3 on every merge. Do not run a local apply while a workflow run is in progress.
- Rollback, rotation, imports and teardown: operate.