Build · Guide

Running DocuSeal for real: production readiness

The DocuSeal tutorial gives you an evaluation stack on localhost. This page lists what changes before you put real documents through it: HTTPS, a database you can back up, the signer’s real IP address, a reliable clock, real email, backups, updates and retention.

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

http://localhost:3000

A domain name, HTTPS only

Database

SQLite in a volume

PostgreSQL, backed up

Email

Mailpit, which catches everything

A real SMTP relay with SPF, DKIM and DMARC

Image

docuseal/docuseal:latest

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.

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

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 HOST at 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-proxy service from the timestamp proxy tutorial to this file and keep the proxy on the internal network only.

  • Keep SECRET_KEY_BASE stable. 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:

  1. Run a full signature from a different device, on a different network if you can.

  2. Open the audit log of that submission.

  3. Check that the IP address is that device’s address, not 127.0.0.1 and not an internal Docker address such as 172.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 (/data in the container): the stored PDFs, and the settings the application keeps there.

  • The .env values, above all SECRET_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 latest in 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

  1. The site is served over HTTPS on your domain, and HTTP redirects to it.

  2. A full signature from another device shows that device’s real IP address in the audit log.

  3. The server clock is synchronised.

  4. A test invitation reaches an external mailbox, and you can retrieve the relay’s delivery log.

  5. The image versions are pinned, and .env is outside version control.

  6. A backup has been taken and restored on another machine.

  7. The retention period is written down, and someone owns deleting expired files.

  8. A test signature passes the review in the evidence file page.

  9. The root certificate, its fingerprint, and the written procedure are stored where your validators can find them.

Are you looking to strengthen the evidential value of your electronic signatures?

Tell us more