Self-hosting DueReason: what you run and what you own
What self-hosting DueReason involves: one Postgres, one pre-built image pulled from GitHub Container Registry, Docker Compose, backups and upgrades you own.
Updated · 7 min read
In short
- Self-hosting runs on one Postgres database plus one pre-built image pulled from GitHub Container Registry, with web, worker and migrator all coming from that same image so they can never drift.
- Download the compose file, env template and quickstart script from this page, run the quickstart script, then docker compose pull && docker compose up -d - no repository to clone, no build step.
- Once it is running, the stack is yours: you back it up, you upgrade it, and you keep it online. This is a beta path with no SLA and no update channel.
- Before your first sign-up, point it at your real https origin, because the authentication layer signs cookies and links to that address and changing it later signs everyone out.
Self-hosting DueReason means running one Postgres database and one application image yourself, with Docker Compose coordinating the three roles the image can run: the web app, a background worker, and a one-shot migrator. It is a beta, no-SLA path: there is no update channel and no support contract, and you own upgrades, backups and uptime once it is running.
What you run
Everything comes from a single image pulled from GitHub Container Registry, so the web app, worker and database migrator can never drift out of sync with each other. The migrator service runs the database migrations and exits; web and worker wait for it to succeed before starting. docker compose pull && docker compose up -d is the default path - no build step, no waiting on the first run. Postgres runs as its own container with a named volume, so your data outlives container restarts and rebuilds.
Requirements
- Docker Engine with the Compose plugin (Compose v2).
- Around 2 GB of RAM free for Postgres, web and worker together.
- One free port for the web app (3000 by default, configurable with
WEB_PORT). openssl, used to generate secrets when the environment file is first created.curl, used to download the compose file, env template and quickstart script below.
Getting set up
Download the four self-host files from this page and run the quickstart script, which writes a .env with freshly generated secrets, then pull and start the stack:
``bash mkdir duereason && cd duereason curl -fsSL https://duereason.com/self-host/docker-compose.yml -o docker-compose.yml curl -fsSL https://duereason.com/self-host/env.example -o .env.example curl -fsSL https://duereason.com/self-host/quickstart.sh -o quickstart.sh curl -fsSL https://duereason.com/self-host/health-check.sh -o health-check.sh chmod +x quickstart.sh health-check.sh ./quickstart.sh docker compose pull docker compose up -d ./health-check.sh # checks liveness, readiness, Postgres and the migration version in one go ``
docker compose pull fetches ghcr.io/override-tech/duereason:latest (web, worker and migrator all come from the same image). That package isn't public yet, so self-host customers get pull access on request through the contact form. Pin a specific released version instead of latest with DUEREASON_TAG=x.y.z in .env or on the command line.
If you put DueReason behind your own TLS-terminating reverse proxy (Caddy, Traefik, nginx or similar), set BETTER_AUTH_URL - and SITE_URL if it differs - to your real https:// origin before the first sign-up. The authentication layer signs cookies and links to that origin, so changing it afterwards signs everyone out and invalidates any outstanding invitation or password-reset links. Keep the web service bound to 127.0.0.1 only and let the proxy be the one thing with a public port.
First run
The first account created at /sign-up becomes that organization's owner. By default, email delivery is set to outbox: confirmation, password-reset and invitation emails are written to a database table rather than sent anywhere, since the compose file ships no mail server. That is enough to confirm your own account and explore the console; for anything beyond a trial, configure Resend so real email goes out. Once you are signed in, you create your organization from the console and add teammates from its Members settings.
Optional pieces
| Variable | What it controls |
|---|---|
WEB_PORT | Port the web service listens on (default 3000). |
DUEREASON_TAG | Pulls a specific released version instead of latest. |
BETTER_AUTH_URL / SITE_URL | Your public https origin; set before the first sign-up. |
EMAIL_DELIVERY | outbox (default, writes to the database) or resend for real email. |
EVIDENCE_STORE | postgres (default, no extra service) or s3 with the matching S3_* variables for an external bucket such as MinIO, Backblaze B2 or AWS. |
WEBHOOK_ALLOWED_PRIVATE_HOSTS | Comma-separated exact hostnames/IPs a webhook endpoint may point at even though they are on your private network (an internal n8n, or an on-prem Zapier/Make relay). Unset by default, which refuses any private target the same way the hosted product does. |
Stripe billing, Turnstile bot-checking, VAPID web push and ClamAV scanning are all optional and left blank until you configure them.
Webhook endpoints normally have to resolve to a public address: that check stops a compromised or malicious account from using your server to reach other hosts on your network (SSRF). WEBHOOK_ALLOWED_PRIVATE_HOSTS relaxes it, one exact host at a time, so you can send webhooks to automation running on the same private network - list only hosts you control, since each entry is a hole in that protection.
Backup
Everything lives in the Postgres service's own volume. A logical dump with pg_dump captures the whole database and can be restored into a fresh volume the same way. There is no automatic backup schedule built into the compose file, so wiring that dump into your own cron job or backup tool is on you.
Upgrade
Upgrading means pulling the newer image and recreating the containers:
``bash docker compose pull docker compose up -d # recreates web/worker/migrator on the new image; migrator re-runs first ``
The migrator runs on every start; if it fails, web and worker stay down rather than serve against a half-migrated schema, so docker compose logs migrator is the first place to look if an upgrade does not come back up cleanly.
Troubleshooting
Run ./health-check.sh (in deploy/self-host/, or the one you downloaded above) first: it checks liveness, the web process's own view of Postgres, Postgres reachability independent of the app, and the applied-vs-shipped migration count in one pass, and its output is safe to paste into a support request. Beyond that: a container that exits immediately citing an invalid environment field means a required variable is missing or malformed; check it against the .env template's own description for that field. If the web service never reports healthy, check the migrator's exit status first - web and worker both wait on it. Stuck at a "confirm your email address" screen almost always means you are still on the default outbox delivery: run docker compose exec web node dist/print-outbox.mjs you@example.com to print the newest outbox emails for that address and the confirmation/invite/reset link inside each one, or switch to Resend for real mail.
What you own
Self-hosting trades the hosted product's managed upgrades and support for full control: you decide when to upgrade, you run the backups, and you are responsible for keeping the service available. There is no SLA on this path and no automatic update channel - every upgrade is a deliberate docker compose pull && docker compose up -d that you run.
Licensing
DueReason is source-available under the Elastic License 2.0: you can run it, read it and modify it, but you can't resell it to others as a hosted or managed service, and you can't move, disable or circumvent its license-key functionality. Self-hosting is free for one organization with up to five members, with all core features included; a yearly license key lifts those limits, signed with Ed25519 and verified entirely offline - no phone-home - and takes effect as soon as you paste it into Settings > License. Questions about self-hosting or commercial licensing: get in touch.
Questions
- Is there a published Docker image I can just pull?
- Not publicly yet. The ghcr.io/override-tech/duereason package isn't public, so self-host customers get pull access on request through /contact instead of a plain docker compose pull. The docker-compose.yml, env template, quickstart script and health-check script are already public, so you can download and review them from this page before asking for access.
- Can I use my own S3 bucket for evidence files?
- Yes. Evidence storage defaults to Postgres, which needs no extra service, but setting EVIDENCE_STORE to s3 and filling in the matching S3 variables points it at MinIO, Backblaze B2, AWS or another S3-compatible bucket.
- Who handles upgrades once it's running?
- You do. Self-hosting has no automatic update channel; upgrading means running docker compose pull && docker compose up -d, and you choose when that happens.
- Does email work out of the box?
- Not real email. The default outbox delivery writes confirmation, reset and invitation emails to a database table instead of sending them, which is enough for a trial; configuring Resend switches on real delivery.
Try self-hosting DueReason
Download the compose file, env template and quickstart script from this guide, then ask for self-host image access and you're running in minutes - no repository to clone.
Ask for self-host accessSources
This guide explains the regulation as we read it; it is not legal advice. Check the official text and your national law, which may add obligations.