Self-Hosting Unitae on a VPS in 10 Minutes
April 23, 20268 min readSelf-hosting
You want to know exactly where your congregation’s data lives. Not a promise from a hosting provider — you want to SSH into the machine and see the database yourself. Good. In ten minutes, you’ll have a running Unitae instance on your own server, behind your own domain, with every feature unlocked. The entire source code is on GitHub under AGPL-3.0, and the self-hosted version is identical to managed.
What you need
A VPS with at least 1 vCPU, 1 GB RAM, and 10 GB of storage (20 GB recommended). A small OVH or Scaleway VPS at around €4–5/month works well (keeps the data in France, consistent with the managed-hosting setup). Ubuntu 22.04 LTS or Debian 12 recommended. You also need a domain name with an A record pointing to your server, Docker and Docker Compose installed, and a Resend account for emails (the free tier is sufficient). To show the maps, you’ll also need a base map file for your area: the documentation explains how to cut one.
On your local machine, you only need SSH access to the server and a text editor. Everything else happens on the server itself.
Clone and configure
SSH into your server, clone the repository, and copy the environment file. Set UNITAE_BASE_URL to your full URL (e.g. https://unitae.your-congregation.org). Generate UNITAE_SESSION_SECRET with openssl rand -hex 32 — it must be at least 32 characters — and do the same for UNITAE_CRON_SECRET. Set RESEND_API_KEY for password resets and notification emails (sign up at resend.com). Pick strong passwords for DB_PASSWORD, DB_RUNTIME_PASSWORD (a different value: it belongs to the role bound by Row-Level Security) and REDIS_PASSWORD. Finally, point the database and Redis at their containers: DB_URL=postgresql://unitae:<DB_PASSWORD>@postgres:5432/unitae and REDIS_HOST=redis.
# Clone the repository
git clone https://github.com/Unitae/unitae.git && cd unitae
# Copy the environment file
cp .env.example .env
# Edit .env with your values
nano .envStart Unitae
Run docker compose up -d to start the full stack. The migrate service applies migrations and exits, then web and worker start. Unitae is now running on port 8080 — open it in a browser and the setup wizard creates your first user and congregation, automatically seeding roles and default programme templates. If anything fails, docker compose logs web shows the application logs. Common issues are a malformed DB_URL or a missing UNITAE_SESSION_SECRET.
docker compose up -d
✓ Unitae is running on localhost:8080Add your domain and TLS
Caddy is the recommended reverse proxy — it handles Let’s Encrypt certificates automatically. The repository ships an example: copy docker/Caddyfile.example to docker/Caddyfile, replace the domain with yours, and uncomment the caddy service in compose.yaml. Point your DNS A record, and HTTPS is live within minutes.
Open ports 80 and 443 in your firewall, then remove the ports line from the web service in compose.yaml: a port Docker publishes bypasses the firewall, and the app should only be reachable through Caddy.
First login and setup
Navigate to your domain. The setup screen walks you through creating your admin account and configuring your congregation. Then work through the onboarding checklist: set your territory structure, invite the territory servant and secretary, and create your first territory card.
Invite other members from Settings › Users. Each invitation sends an email with a link to create an account. Members receive access appropriate to their role — publishers see their own territories, and those with the rights reach congregation-wide data.
One last step not to skip: three scheduled tasks. Without them, no notification email goes out. Add them to the server’s crontab (crontab -e), with your UNITAE_CRON_SECRET and your domain:
# Notifications every 5 minutes, clean-up and board expiries every day
UNITAE_CRON_SECRET=…
*/5 * * * * curl -s -H "Authorization: Bearer $UNITAE_CRON_SECRET" https://unitae.example.org/cron/process-notifications
0 3 * * * curl -s -H "Authorization: Bearer $UNITAE_CRON_SECRET" https://unitae.example.org/cron/retention
0 7 * * * curl -s -H "Authorization: Bearer $UNITAE_CRON_SECRET" https://unitae.example.org/cron/board-expirationsKeeping it updated
Updating is three commands: git pull, docker compose pull, then docker compose up -d — the migrate service applies migrations before web and worker restart. Back up the database before each update, and subscribe to GitHub releases to be notified of new versions. For backups, add a daily cron job that dumps PostgreSQL to a file and copies it offsite. Keep at least seven days of backups and test restores periodically. You now have a self-hosted instance that is entirely yours — and if you contribute improvements back, every congregation using Unitae benefits.