DocuSeal with Docker Compose

With SQLite, the default

• x86-64 PC or NAS (linux/amd64): every image has a build.
• Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
• Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for app. No image for this hardware; the builder leaves the app out.

With PostgreSQL

• x86-64 PC or NAS (linux/amd64): every image has a build.
• Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
• Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for app. No image for this hardware; the builder leaves the app out.

With SQLite, the default

This is exactly what the builder writes for DocuSeal alone on example.org: the official definition with its published ports removed and Caddy added in front. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: DocuSeal
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- DocuSeal (sign.example.org) ----
  # Source: https://github.com/docusealco/docuseal/blob/master/README.md (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/docker-compose.yml (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/config/database.yml (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/Dockerfile (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/config/environments/production.rb (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/app/controllers/setup_controller.rb (checked 2026-10-03)
  # Changed: This is the README's docker run line written as a compose service, the SQLite set-up DocuSeal uses by default. Its '-p 3000:3000' is removed; Caddy reaches docuseal-app:3000 on the proxy network. Its '-v.:/data' (the current folder) becomes ./data, so the database lands in ./docuseal/data/docuseal/db.sqlite3 (the image's WORKDIR is /data/docuseal).
  #          FORCE_SSL=${HOST} is taken from the compose file: with it DocuSeal treats every request as HTTPS behind the proxy (assume_ssl and force_ssl). HOST is sign.example.org in .env.
  docuseal-app:
    image: "docuseal/docuseal"
    container_name: "docuseal-app"
    volumes:
      - "./docuseal/data:/data"
    environment:
      FORCE_SSL: "${DOCUSEAL_HOST}"
    networks:
      proxy: {}

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"

volumes:
  caddy-data:
  caddy-config:

With PostgreSQL

This is what the builder's code writes for DocuSeal alone on example.org from the project's PostgreSQL setup (the builder on the front page still writes the SQLite version, so copy this one from here): the official definition with its published ports removed and Caddy added in front. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: DocuSeal
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- DocuSeal (sign.example.org) ----
  # Source: https://github.com/docusealco/docuseal/blob/master/docker-compose.yml (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/README.md (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/config/environments/production.rb (checked 2026-10-03)
  # Source: https://github.com/docusealco/docuseal/blob/master/app/controllers/setup_controller.rb (checked 2026-10-03)
  # Source: https://www.postgresql.org/docs/current/upgrading.html (checked 2026-10-03)
  # Changed: The compose file's own caddy service (caddy reverse-proxy --from $HOST --to app:3000, publishing 80 and 443) is left out: the builder's one proxy does that job for every app. The app's '3000:3000' port is removed; Caddy reaches docuseal-app:3000 on the proxy network.
  #          The example database password 'postgres' is a generated value in .env, used in POSTGRES_PASSWORD and in DATABASE_URL. HOST, which the file reads from your shell (sudo HOST=your-domain-name.com docker compose up), is sign.example.org in .env.
  #          postgres sits only on the internal network it shares with the app and publishes no port.
  docuseal-app:
    depends_on:
      docuseal-postgres:
        condition: "service_healthy"
    image: "docuseal/docuseal:latest"
    container_name: "docuseal-app"
    volumes:
      - "./docuseal/docuseal:/data/docuseal"
    environment:
      FORCE_SSL: "${DOCUSEAL_HOST}"
      DATABASE_URL: "postgresql://postgres:${DOCUSEAL_POSTGRES_PASSWORD}@postgres:5432/docuseal"
    networks:
      proxy: {}
      docuseal-backend:
        aliases:
          - "app"
  docuseal-postgres:
    image: "postgres:18"
    container_name: "docuseal-postgres"
    volumes:
      - "./docuseal/pg_data:/var/lib/postgresql/18/docker"
    environment:
      POSTGRES_USER: "postgres"
      POSTGRES_PASSWORD: "${DOCUSEAL_POSTGRES_PASSWORD}"
      POSTGRES_DB: "docuseal"
    healthcheck:
      test:
        - "CMD-SHELL"
        - "pg_isready -U postgres"
      interval: "5s"
      timeout: "5s"
      retries: 5
    networks:
      docuseal-backend:
        aliases:
          - "postgres"

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"
  docuseal-backend:
    internal: true

volumes:
  caddy-data:
  caddy-config:

With SQLite, the default

DocuSeal needs no secret here; the builder adds nothing you have to fill in by hand.

# .env for DocuSeal, from dankhost.com/app/docuseal/. Nothing here is secret.
# Keep this file private (chmod 600).

# DocuSeal
DOCUSEAL_HOST=sign.example.org

With PostgreSQL

The secret is left blank here on purpose: a password printed on a public page is the same for everyone who copies it. Fill it with random letters and digits as in How to run it.

# .env for DocuSeal, from dankhost.com/app/docuseal/. Fill the blank secret before starting.
# Keep this file private (chmod 600).

# DocuSeal
DOCUSEAL_HOST=sign.example.org
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
DOCUSEAL_POSTGRES_PASSWORD=

With SQLite, the default

• This is the README's docker run line written as a compose service, the SQLite set-up DocuSeal uses by default. Its '-p 3000:3000' is removed; Caddy reaches docuseal-app:3000 on the proxy network. Its '-v.:/data' (the current folder) becomes ./data, so the database lands in ./docuseal/data/docuseal/db.sqlite3 (the image's WORKDIR is /data/docuseal).
• FORCE_SSL=${HOST} is taken from the compose file: with it DocuSeal treats every request as HTTPS behind the proxy (assume_ssl and force_ssl). HOST is sign.example.org in .env.

Notes for DocuSeal behind the proxy

• Open https://sign.example.org straight after the first start: the setup page there creates the first account, for whoever opens it first, and asks for the app URL: give https://sign.example.org.
• DocuSeal sends signing requests by e-mail only after you add an SMTP server in its settings; without one, share the signing links yourself.
• Neither the README's docker run line nor its compose file sets a restart policy, so after a reboot DocuSeal stays down until docker compose up -d. Add restart: unless-stopped to the service if you want it to come back by itself.
• The image has no tag, which is latest: each pull takes the newest release.

With PostgreSQL

• The compose file's own caddy service (caddy reverse-proxy --from $HOST --to app:3000, publishing 80 and 443) is left out: the builder's one proxy does that job for every app. The app's '3000:3000' port is removed; Caddy reaches docuseal-app:3000 on the proxy network.
• The example database password 'postgres' is a generated value in .env, used in POSTGRES_PASSWORD and in DATABASE_URL. HOST, which the file reads from your shell (sudo HOST=your-domain-name.com docker compose up), is sign.example.org in .env.
• postgres sits only on the internal network it shares with the app and publishes no port.

Notes for DocuSeal behind the proxy

• Open https://sign.example.org straight after the first start: the setup page there creates the first account, for whoever opens it first, and asks for the app URL: give https://sign.example.org.
• postgres:18 keeps its data in /var/lib/postgresql/18/docker, the path the file mounts ./pg_data at.
• The file sets no restart policy on either service, so after a reboot DocuSeal stays down until docker compose up -d. Add restart: unless-stopped to both services if you want them to come back by themselves.

With SQLite, the default

DocuSeal publishes no backup procedure. With SQLite everything is in ./data: the database (data/docuseal/db.sqlite3) and the uploaded and signed documents.

Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.

# BACKUP.md built at dankhost.com for: DocuSeal

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## DocuSeal

DocuSeal publishes no backup procedure. With SQLite everything is in ./data: the database (data/docuseal/db.sqlite3) and the uploaded and signed documents.

What this compose mounts:
- ./docuseal/data (/data in docuseal-app)
  BACK UP: db.sqlite3 (templates, submissions, users, audit trail) and the stored documents and signatures.

1. Stop docuseal-app. Stopping it keeps the SQLite database from changing mid-copy.

    docker compose stop docuseal-app

2. Copy while docuseal-app is stopped:

    tar czf "$BACKUP/docuseal-data.tar.gz" ./docuseal/data

3. Start it again:

    docker compose start docuseal-app

Restore check:

    tar tzf "$BACKUP/docuseal-data.tar.gz" > /dev/null && echo OK

Put a copy back (with docuseal-app stopped):

    tar xzf "$BACKUP/docuseal-data.tar.gz"   # recreates ./docuseal/data; move the old folder aside first

Stop it, put ./docuseal/data back, start it.

Sources:
- DocuSeal: config/database.yml (SQLite at $WORKDIR/db.sqlite3 when DATABASE_URL is empty): https://github.com/docusealco/docuseal/blob/master/config/database.yml (checked 2026-10-03)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-10-03)

With PostgreSQL

DocuSeal publishes no backup procedure. With PostgreSQL the database is a pg_dump of the postgres service; the documents are in ./docuseal.

Below is the BACKUP.md for the PostgreSQL version of the compose file above, written by the same code as the builder's: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check.

# BACKUP.md built at dankhost.com for: DocuSeal

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## DocuSeal

DocuSeal publishes no backup procedure. With PostgreSQL the database is a pg_dump of the postgres service; the documents are in ./docuseal.

What this compose mounts:
- ./docuseal/docuseal (/data/docuseal in docuseal-app)
  BACK UP: uploaded and signed documents and their attachments.
- ./docuseal/pg_data (/var/lib/postgresql/18/docker in docuseal-postgres)
  COVERED BY THE COMMAND BELOW: PostgreSQL's data files; the pg_dump below is the copy to keep.

1. Database dump for docuseal-postgres:

    docker compose exec -T docuseal-postgres pg_dump -U postgres docuseal > "$BACKUP/docuseal.sql"

   pg_dump with the user and database of the file: postgres and docuseal.

2. Copy (DocuSeal keeps running):
   pg_dump is consistent while the app runs: the dump is a snapshot of the database at the moment it started (PostgreSQL docs).

    tar czf "$BACKUP/docuseal-docuseal.tar.gz" ./docuseal/docuseal

Restore check:

    grep -c 'PostgreSQL database dump complete' "$BACKUP/docuseal.sql"   # 1 means pg_dump finished
    tar tzf "$BACKUP/docuseal-docuseal.tar.gz" > /dev/null && echo OK

Put a copy back (with DocuSeal stopped):

    tar xzf "$BACKUP/docuseal-docuseal.tar.gz"   # recreates ./docuseal/docuseal; move the old folder aside first

Into a fresh database, before DocuSeal starts against it:

    docker compose up -d docuseal-postgres
    docker compose exec -T docuseal-postgres psql -U postgres docuseal < "$BACKUP/docuseal.sql"

Put ./docuseal/docuseal back, then:

    docker compose up -d

Sources:
- PostgreSQL docs: pg_dump (consistent backups while the database is in use): https://www.postgresql.org/docs/current/app-pgdump.html (checked 2026-10-03)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-10-03)

With SQLite, the default

What docker compose pull does depends only on how each image line in the compose file above is tagged. For DocuSeal as this page writes it:

What DocuSeal's docs say about updating

DocuSeal publishes no update procedure for this setup; the steps below are Docker's generic method.

The steps

1. Back up first, as in Back it up above. An update can migrate DocuSeal's data on its first start; the copy is the way back.
2. Download the new images. Running containers are not touched yet:

   docker compose pull

3. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:

   docker compose up -d

4. Watch DocuSeal start (Ctrl+C stops following the log, not the app):

   docker compose logs -f docuseal-app

5. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:

   docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30

With PostgreSQL

What docker compose pull does depends only on how each image line in the compose file above is tagged. For DocuSeal as this page writes it:

What DocuSeal's docs say about updating

DocuSeal publishes no update steps of its own. For the PostgreSQL set-up the database's own rule applies, from PostgreSQL's Upgrading a PostgreSQL Cluster page:

• DocuSeal and PostgreSQL are updated separately, one tag at a time. docuseal/docuseal:latest takes each new DocuSeal release on docker compose pull; the postgres tag, 18, takes every 18.x release, and PostgreSQL says minor releases never change the storage format, so that is safe.
• A new PostgreSQL major version cannot open the data of the old one: the page says to dump and restore it (or use pg_upgrade). This file mounts the data at /var/lib/postgresql/18/docker, a path with the version in it, so the mount changes with the tag. With this file: stop DocuSeal, dump, check the dump, move the data folder aside, edit the tag and the mount path, start the database alone, load the dump, start the rest:

  docker compose stop docuseal-app
  docker compose exec -T docuseal-postgres pg_dump -U postgres docuseal > docuseal-pg18.sql
  grep -c 'PostgreSQL database dump complete' docuseal-pg18.sql   # must print 1 before you go on
  docker compose stop docuseal-postgres && mv docuseal/pg_data docuseal/pg_data-18
  docker compose up -d docuseal-postgres   # after editing the tag and /var/lib/postgresql/18/docker to the new version
  until docker compose exec -T docuseal-postgres pg_isready -h 127.0.0.1 -U postgres; do sleep 2; done   # waits until the first-start setup is over
  docker compose exec -T docuseal-postgres psql -U postgres -d docuseal --set ON_ERROR_STOP=on < docuseal-pg18.sql
  docker compose up -d

• Keep docuseal/pg_data-18 until DocuSeal has run well for a while: putting it back with the old tag is the way back.

Source: PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-10-03

The steps

1. Back up first, as in Back it up above. An update can migrate DocuSeal's data on its first start and its database with it; the copy is the way back.
2. Download the new images. Running containers are not touched yet:

   docker compose pull

3. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:

   docker compose up -d

4. Watch DocuSeal start (Ctrl+C stops following the log, not the app):

   docker compose logs -f docuseal-app

5. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:

   docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30