Deployment & releases

dembrane has a short, opinionated path from a merged PR to production. main continuously deploys to a staging environment; production ships from release tags roughly every two weeks. This page covers the branches, the environments, the GitOps repo, the Docker images, and the migration ritual. The canonical engineering docs are echo/docs/branching_and_releases.md and echo/docs/database_migrations.md - this page is the orientation and the gotchas.

The environments#

Each environment has matching dashboard.*, portal.* and directus.* subdomains.

The development flow#

main ──────────●──────────────●────  (auto-deploys to Echo Next)
       \      ↗ PR             |
        feat/ECHO-123          |
                \              |
                 testing ────→ dashboard.testing.dembrane.com

1. *Branch off main - feat/ECHO-xxx-description or similar.
2. Develop on the feature branch.
3. (Optional) test on the testing environment - merge your branch into testing to deploy to dashboard.testing.dembrane.com.
4. Open a PR to main.
5. After merge - changes auto-deploy to Echo Next (~2 min).
6. After you’re done testing - reset testing back to main.

The testing-branch reset rule#

testing is shared and unprotected - anyone can push to it. So before you use it, check nobody else is mid-flight, and when you’re done, reset it:

# before: is testing ahead of main? (someone else's work?)
git log main..testing --oneline

# after: hand it back clean
git checkout testing
git reset --hard origin/main
git push --force

The release process#

Releases align with the two-week Linear cycles:

1. Accumulate changes on main through the cycle.
2. Pre-release checks (the easy-to-forget ones):
   • New env vars - anything added as a field on AppSettings in settings.py, or exported from the frontend config.ts. If a release needs a new var, it must be set in the GitOps repo before the tag, or the new pods crash-loop. Check the env-flag/feature-flag state too - make sure a half-built feature isn’t about to light up in prod.
   • Directus migrations - run any data/schema migrations (see below).
   • GitOps env - update deployment env vars in the GitOps repo if needed.
3. Tag and release - cut a GitHub release from a commit on main.
4. The release auto-deploys to production:
   • Backend - new image tags are picked up by the GitOps repo (dembrane/echo-gitops); Argo CD auto-syncs them.
   • Frontend - auto-deploys via Vercel.

Hotfixes#

When a critical prod bug needs fixing but main has unreleased changes that shouldn’t go out, branch the fix off the released tag, not off main, and release it on its own. The exact cherry-pick recipe is in echo/docs/branching_and_releases.md - follow it rather than improvising.

The GitOps repo#

Production infra lives in a separate repo, dembrane/echo-gitops:

• Terraform - DigitalOcean infrastructure (clusters, managed Postgres, Spaces, Valkey).
• Helm - the chart that templates the Kubernetes resources for each service.
• Argo CD - continuous delivery; it watches the repo and auto-syncs the cluster to match. New image tags from a release are reconciled by Argo, not pushed by hand.

So a backend release is really: build image → bump tag in echo-gitops → Argo syncs. Changing a prod env var means editing the GitOps repo (often a sealed/encrypted value), not the cluster directly.

The Docker images#

Four service images are built from the monorepo:

The frontend isn’t a container in this flow - it deploys via Vercel.

Database migrations#

Schema lives in Directus and is managed with directus-sync. The ritual (echo/docs/database_migrations.md):

1. cd echo/directus
2. Run ./sync.sh and choose push (option 1) to apply the schema snapshot.
3. Run any required raw SQL on the database (psql -h postgres -p 5432 -U dembrane; default dev password dembrane), e.g. CREATE EXTENSION vector; for pgvector.

Some changes are two-step and order-sensitive - deploy the code first, then run the SQL. The membership unique indexes (one active membership per user per org/workspace), which the invite-race fix in api/v2/_invite_helpers.py depends on, are the canonical example: deploy the API change, then create the partial unique indexes. If index creation fails on a duplicate key, dedupe the active rows first, then re-run.

Where the rules live#

• echo/docs/branching_and_releases.md - the authoritative branch/release/hotfix process.
• echo/docs/database_migrations.md - the migration ritual and the index recipes.
• echo/docs/adr/ - the ADRs (0001–0005) that explain why the data and billing model look the way they do; relevant when a release touches roles, seats, tiers or invites. See roles & policies in code.

Related

• Architecture
• Local development
• The data model
• Background jobs & scheduler
• Self-hosting (external)