Deployment

The shape of it

One container running the FastAPI app on port 8000. Postgres is managed elsewhere, Redis is optional and external. There is no production Compose file; the deploy image is docker/deploy/Dockerfile, which is the development image without hot reload.

How a release ships

1. Merge to development

   Pull requests target development. When one merges, CI runs and then calls a deploy hook for the staging service.

2. Cut a release branch

   ./scripts/ci/create-release.sh 0.3.0

   This branches from development, bumps the version in pyproject.toml, optionally updates the contributor list, and opens a pull request back into development.

3. Merge the release pull request

   Merging a branch named release/* triggers automation that merges development into main, generates a changelog, tags the version and publishes a GitHub release.

4. Production deploys itself

   The push to main fires the production deploy hook.

Name release branches release/0.3.0, without a v. The tag is created by adding one, so release/v0.3.0 would produce a tag of vv0.3.0.

Running your own instance

The application is MIT licensed and self-hostable. Anything that can run a container will do. Work through this list before you point a real phone number at it.

Security

• MOCK_WHATSAPP must be false. Both templates ship it as true. Left on, it disables webhook signature verification and exposes an unauthenticated endpoint that accepts messages claiming to be from any user. This is the single most important line in your configuration.
• Terminate TLS in front of the app. It serves plain HTTP and the repository contains no proxy or certificate handling. Meta requires HTTPS.
• /metrics has no authentication. If the service is public, so are your metrics. Restrict it at the proxy.
• Inject secrets as real environment variables or point TWIGA_ENV at a mounted file. Do not bake an .env into an image.

Configuration

• Set ENVIRONMENT=production. Below that value, Redis never connects, rate limiting is skipped, welcome templates are not sent, and unknown numbers are turned into test accounts.
• Set all four rate limit variables. Three of them are in neither template, and missing any one silently disables enforcement.
• Enable pgvector on the managed database. The extension is not created by any migration.
• If you are not using the provided Dockerfile, install fontconfig and libgraphite2-3, which LaTeX rendering needs.

Migrations

Nothing applies them for you. Neither the image nor application startup runs Alembic, so alembic upgrade head is a deliberate step in your deploy process. Startup only checks that the database answers.

Scheduled jobs

Three jobs in scripts/crons/ approve users, mark them inactive and send re-engagement reminders. Nothing in the repository schedules them; you need an external scheduler. Without one, approvals never complete. See Monitoring.

Before you scale out

The repository assumes one process. There is no worker count, no gunicorn, no autoscaling configuration. Two things break or degrade with multiple replicas:

• Prometheus counters are per process, so each replica reports its own series and the scrape configuration expects a single target.
• The scheduled jobs take no lock. Two schedulers means duplicate messages to real teachers.

Rate limiting itself is Redis backed and scales fine, as does the request path.