Self-host ExoSeal
ExoSeal runs with one docker-compose file on your own server and with your own login provider. Then everything is yours.
OperationRequirements
You need a server with Docker and Docker Compose, a domain with HTTPS through a reverse proxy such as Caddy or nginx, and an OIDC sign-in provider with PKCE (S256).
Create the configuration
Download docker-compose.yml and .env.example from the repository into an empty folder and copy .env.example to .env. Set your own database password and PUBLIC_URL to your address, for example https://seal.example.com. The .env file never belongs in a repository.
Set up sign-in
Enter OIDC_METADATA_ADDRESS, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET of your provider. At the provider, register the redirect URI PUBLIC_URL/api/v1/auth/callback.
Who may send
Set ALLOWED_EMAIL_DOMAINS and/or ALLOWED_EMAILS. Only these addresses can create links. Once sign-in is active, at least one entry is required.
Put a reverse proxy in front
The proxy forwards to the frontend (port 3000) and handles TLS. Set TRUSTED_PROXY_HOPS to 1 if exactly one proxy sits in front, so the per-visitor limit counts correctly. If the real IP arrives in a header of its own instead (Cloudflare: CF-Connecting-IP), set CLIENT_IP_HEADER to its name, but only if the server can be reached solely through that proxy.
Start
Start everything with docker compose pull, then docker compose up -d. The ready-made images come from the GitHub Container Registry, nothing is built. The frontend health check reports when everything runs. Then open your address and sign in.
Optional: notifications, imprint, reports
With SMTP_* or WEBHOOK_URL you get notified when a request was answered. The IMPRINT_* settings (name, address, email, representatives, phone, register, VAT ID) fill the imprint and the terms of use, PRIVACY_SERVICES names services in front of the instance such as Cloudflare in the privacy policy, ABUSE_EMAIL shows a contact address for abuse reports.
Good to know
- Back up the database without the secrets table. Secrets are ephemeral, a backup would bring back ones that were already opened.
- Do not enable access logs that contain paths: the address holds the ID of the secret.
- The detailed operating notes are in the docs folder of the project.
Common questions.
01Do I need my own login provider?
Yes. ExoSeal signs users in through an OpenID Connect provider. You decide which email addresses or domains may sign in with an allowlist.
02Which license applies?
ExoSeal is licensed under AGPL-3.0. You may run and modify it yourself. Changes to a publicly operated instance must be published as well.
03What should I watch for with the reverse proxy?
The number of proxies in front of ExoSeal must match the TRUSTED_PROXY_HOPS setting. Otherwise all visitors share the same abuse limit.
04Do I need a mail server?
No. Notifications by mail or webhook are optional.
Built by
ExostructionMaker of ExoSealExoSeal is built by Exostruction, a small software company from Bavaria. The source code is open (AGPL-3.0).This guide describes the default settings of ExoSeal. On self-hosted instances individual values may differ.