services:
app:
image: docuseal/docuseal:<PINNED_VERSION>
depends_on:
postgres:
condition: service_healthy
volumes:
- ./docuseal:/data
environment:
- FORCE_SSL=${HOST}
- DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/docuseal
- SECRET_KEY_BASE=${SECRET_KEY_BASE}
restart: unless-stopped
postgres:
image: postgres:<PINNED_VERSION>
volumes:
- ./pg_data:/var/lib/postgresql/data
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
- POSTGRES_DB=docuseal
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
restart: unless-stopped
caddy:
image: caddy:<PINNED_VERSION>
command: caddy reverse-proxy --from ${HOST} --to app:3000
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./caddy:/data
environment:
- HOST=${HOST}
restart: unless-stopped
This is the Build stage. It builds on the DocuSeal tutorial, and each item feeds the evidence file checklist. The compose file is a starting point. Check it against DocuSeal’s current official docker-compose.yml before you rely on it.
1. What changes from the evaluation stack
| Area | Evaluation stack | Production |
|---|---|---|
Address |
A domain name, HTTPS only |
|
Database |
SQLite in a volume |
PostgreSQL, backed up |
Mailpit, which catches everything |
A real SMTP relay with SPF, DKIM and DMARC |
|
Image |
|
A pinned version you upgrade on purpose |
Secrets |
Placeholders in the compose file |
Kept outside the repository |
Signer IP |
Not an issue on localhost |
Must be tested behind the proxy |
Backups |
None |
Scheduled, encrypted, restore-tested |
Retention |
Not defined |
Defined and enforced |
2. A production-shaped stack
DocuSeal’s official compose file runs three services: the app, PostgreSQL, and Caddy as a reverse proxy that obtains HTTPS certificates automatically for your domain. Start from that shape.
Put the values in a .env file next to it, outside version control:
HOST=docuseal.example.com
POSTGRES_PASSWORD=<long-random-password>
SECRET_KEY_BASE=<long-random-string>
Notes:
-
Point your DNS record for
HOSTat the server before you start, so Caddy can obtain the certificate. -
Do not publish the app or the database port. Only Caddy should be reachable, on ports 80 and 443.
-
If your DocuSeal build has no Custom Headers field, add the
tsa-proxyservice from the timestamp proxy tutorial to this file and keep the proxy on the internal network only. -
Keep
SECRET_KEY_BASEstable. Changing it makes stored settings unreadable, including the encrypted TSA header.
3. The signer’s real IP address
The IP address in the audit log is evidence that the signer was where you say they were. Behind a reverse proxy, an application can record the proxy’s own address instead. DocuSeal’s logs use the client address that Rails derives from the forwarded headers, so the proxy must pass them on, and the application must trust that proxy.
You cannot tell from the configuration alone whether it works. Test it:
-
Run a full signature from a different device, on a different network if you can.
-
Open the audit log of that submission.
-
Check that the IP address is that device’s address, not
127.0.0.1and not an internal Docker address such as172.x.x.x.
If it is wrong, fix the proxy headers or the trusted proxy settings before go-live. If you put another load balancer or CDN in front of Caddy, repeat the test, because each layer can replace the address.
4. One reliable clock
The document and the log should take their time from the same reliable source, and the gap between them should be zero. Synchronise the server’s clock with a trusted time source (for example chrony or systemd-timesyncd) and check it is running. Docker containers share the host’s clock, so fix it on the host.
The RFC 3161 timestamps are independent of your clock, because the timestamp authority supplies the time. That is why timestamping the signed PDF and the audit log is valuable: it fixes the date even if your own clock is wrong. Still, keep your clock correct, so the visible times in the document and log agree.
5. Real email delivery
Remove the Mailpit variables and configure a real SMTP relay under Settings → Email, or with the SMTP_* variables. Then:
-
Send from a domain you control, with SPF, DKIM and DMARC set up, or invitations will land in spam.
-
Keep the relay’s delivery logs. They are your proof that an invitation was sent and accepted. See the evidence file checklist.
-
Send a test invitation to an external mailbox and check it arrives.
6. Backups and restore
What you must be able to recover:
-
The database: a scheduled dump of PostgreSQL.
-
The data directory (
/datain the container): the stored PDFs, and the settings the application keeps there. -
The
.envvalues, above allSECRET_KEY_BASE. Without it, stored settings cannot be read. -
The signing certificate and key, and the offline root CA key if you created your own (see the root CA tutorial).
Rules:
-
Encrypt backups, and store them away from the server.
-
Test a restore on a separate machine. A backup you have never restored is not yet a backup.
-
Keep the backups at least as long as your retention period, and keep them consistent with it. Deleting a record from production but not from backups is a retention problem too.
7. Updates
-
Pin the image version. Do not run
latestin production, because a restart can silently upgrade you. -
Read the release notes, test the upgrade on a copy of your data, then upgrade production.
-
Check your signing certificate, timestamp settings and a test signature after each upgrade.
-
DocuSeal is open source under the AGPL. If you modify it or embed it in something you distribute, review the licence first.
-
Record the version in use on the date of each signature. See the evidence file page.
8. Retention, privacy and access
The evidence file holds personal data: names, email addresses, IP addresses.
-
Retention: decide how long you keep each file, and delete after that. A period aligned with the limitation period for disputes is one common approach; the right period depends on your jurisdiction and your documents, so confirm it with your legal counsel.
-
Minimisation: collect only what you need as evidence. Do not add fields you will not use.
-
Information: link the privacy notice in the invitation email and the consent text (see step 6 of the DocuSeal tutorial).
-
Encryption at rest: encrypt the disk or volume that holds the data directory, the database and the backups.
-
Access: keep the number of administrator accounts small, use strong unique passwords, and keep the server and database off the public network apart from ports 80 and 443.
-
Logs: watch application logs for failed signing jobs. A failed timestamp call fails the signing job, so an unreachable timestamp server means signatures that do not complete.
9. Go-live checklist
-
The site is served over HTTPS on your domain, and HTTP redirects to it.
-
A full signature from another device shows that device’s real IP address in the audit log.
-
The server clock is synchronised.
-
A test invitation reaches an external mailbox, and you can retrieve the relay’s delivery log.
-
The image versions are pinned, and
.envis outside version control. -
A backup has been taken and restored on another machine.
-
The retention period is written down, and someone owns deleting expired files.
-
A test signature passes the review in the evidence file page.
-
The root certificate, its fingerprint, and the written procedure are stored where your validators can find them.