Documenso with Docker Compose

What Documenso needs

Only figures Documenso's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.

On top of this, Caddy (the reverse proxy in the file) is a single small container. Documenso itself runs as 2 containers: documenso-database, documenso.

Which hardware Documenso has images for

Read from each image's manifest list in its registry (anonymous, read-only) when this page was built. An app counts for a CPU only if every one of its images lists it.

• 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 documenso. No image for this hardware; the builder leaves the app out.

A manifest says an image exists for a CPU, not how well Documenso runs on it: a build for arm64 or arm/v7 can still be too slow or need more memory than the board has. The RAM and disk Documenso publishes are in the table above and, for a whole set of apps against a Raspberry Pi, on Will it run on my machine?. A tag like latest can move to a new digest after the date checked.

docker-compose.yml

This is exactly what the builder writes for Documenso 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: Documenso
# 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"

  # ---- Documenso (documenso.example.org) ----
  # Source: https://github.com/documenso/documenso/blob/main/docker/production/compose.yml (checked 2026-10-08)
  # Source: https://docs.documenso.com/docs/self-hosting/deployment/docker-compose (checked 2026-10-08)
  # Source: https://docs.documenso.com/docs/self-hosting/configuration/signing-certificate/local (checked 2026-10-08)
  # Source: https://docs.documenso.com/docs/self-hosting/getting-started/requirements (checked 2026-10-08)
  # Source: https://docs.documenso.com/docs/self-hosting/configuration/email (checked 2026-10-08)
  # Source: https://docs.documenso.com/docs/self-hosting/maintenance/backups (checked 2026-10-08)
  # Source: https://docs.documenso.com/docs/self-hosting/maintenance/upgrades (checked 2026-10-08)
  # Changed: Removed the documented '${PORT:-3000}:${PORT:-3000}' port; Caddy reaches documenso:3000 on the proxy network.
  #          The file reads every value from .env with ${VAR:?err}. Here the required ones from the Docker Compose page are written under environment: the database user and name documenso, NEXT_PUBLIC_WEBAPP_URL https://documenso.example.org, and the database URL with the generated password. NEXTAUTH_SECRET and both encryption keys are generated (the page generates them with openssl rand). The optional variables the file passes through empty (Google sign-in, S3 uploads, other mail transports, signup switches) are left out, so their defaults apply.
  #          The SMTP settings use the page's smtp-auth transport and come from .env, where you fill them in. NEXT_PRIVATE_SMTP_FROM_NAME is the page's example, Documenso.
  #          The signing certificate is ./cert.p12 next to this file instead of /opt/documenso/cert.p12 on the host, mounted read-only at the same path in the container; NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH is the file's default for it.
  documenso-database:
    image: "postgres:15"
    container_name: "documenso-database"
    environment:
      POSTGRES_USER: "documenso"
      POSTGRES_PASSWORD: "${DOCUMENSO_POSTGRES_PASSWORD}"
      POSTGRES_DB: "documenso"
    healthcheck:
      test:
        - "CMD-SHELL"
        - "pg_isready -U documenso -d documenso"
      interval: "10s"
      timeout: "5s"
      retries: 5
    volumes:
      - "documenso-database:/var/lib/postgresql/data"
    networks:
      documenso-backend:
        aliases:
          - "database"
  documenso:
    image: "documenso/documenso:latest"
    container_name: "documenso"
    depends_on:
      documenso-database:
        condition: "service_healthy"
    environment:
      PORT: "3000"
      NEXTAUTH_SECRET: "${DOCUMENSO_NEXTAUTH_SECRET}"
      NEXT_PRIVATE_ENCRYPTION_KEY: "${DOCUMENSO_NEXT_PRIVATE_ENCRYPTION_KEY}"
      NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY: "${DOCUMENSO_NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY}"
      NEXT_PUBLIC_WEBAPP_URL: "https://documenso.example.org"
      NEXT_PRIVATE_INTERNAL_WEBAPP_URL: "http://localhost:3000"
      NEXT_PRIVATE_DATABASE_URL: "postgresql://documenso:${DOCUMENSO_POSTGRES_PASSWORD}@database:5432/documenso"
      NEXT_PRIVATE_SMTP_TRANSPORT: "smtp-auth"
      NEXT_PRIVATE_SMTP_HOST: "${DOCUMENSO_SMTP_HOST}"
      NEXT_PRIVATE_SMTP_PORT: "${DOCUMENSO_SMTP_PORT}"
      NEXT_PRIVATE_SMTP_USERNAME: "${DOCUMENSO_SMTP_USERNAME}"
      NEXT_PRIVATE_SMTP_PASSWORD: "${DOCUMENSO_SMTP_PASSWORD}"
      NEXT_PRIVATE_SMTP_FROM_NAME: "Documenso"
      NEXT_PRIVATE_SMTP_FROM_ADDRESS: "${DOCUMENSO_SMTP_FROM_ADDRESS}"
      NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH: "/opt/documenso/cert.p12"
      NEXT_PRIVATE_SIGNING_PASSPHRASE: "${DOCUMENSO_SIGNING_PASSPHRASE}"
    volumes:
      - "./documenso/cert.p12:/opt/documenso/cert.p12:ro"
    networks:
      proxy: {}
      documenso-backend: {}

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"
  documenso-backend:
    internal: true

volumes:
  caddy-data:
  caddy-config:
  documenso-database:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for documenso.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.

# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.

# Documenso
documenso.example.org {
	reverse_proxy documenso:3000
}

Already running nginx, Nginx Proxy Manager, Caddy or Traefik? The reverse-proxy settings Documenso needs, for all four, each cited to Documenso's own docs.

.env

The secrets are left blank here on purpose: a password printed on a public page is the same for everyone who copies it. The builder fills them with random letters and digits made in your browser.

# .env for Documenso, from dankhost.com/app/documenso/. Fill the blank secrets before starting.
# Keep this file private (chmod 600).

# Documenso
# 32 random letters and digits: the builder fills this in your browser
DOCUMENSO_POSTGRES_PASSWORD=
# 48 random letters and digits: the builder fills this in your browser
DOCUMENSO_NEXTAUTH_SECRET=
# 48 random letters and digits: the builder fills this in your browser
DOCUMENSO_NEXT_PRIVATE_ENCRYPTION_KEY=
# 48 random letters and digits: the builder fills this in your browser
DOCUMENSO_NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=
# Documenso cannot run without email: the Docker Compose page lists SMTP credentials among the prerequisites. Put your mail provider's server, port (587 here; NEXT_PRIVATE_SMTP_SECURE=true for 465), login and sender address in these five lines.
DOCUMENSO_SMTP_HOST=smtp.example.org
DOCUMENSO_SMTP_PORT=587
DOCUMENSO_SMTP_USERNAME=change-me@example.org
DOCUMENSO_SMTP_PASSWORD=change-me
DOCUMENSO_SMTP_FROM_ADDRESS=change-me@example.org
# The password you give the .p12 signing certificate when you create it (see the notes). A certificate without a password fails to sign.
DOCUMENSO_SIGNING_PASSPHRASE=change-me

Changes from the official file

Besides prefixing every service, container, volume, folder and variable with documenso (so any set of apps can share one file), these are all the differences from what the project documents:

• Removed the documented '${PORT:-3000}:${PORT:-3000}' port; Caddy reaches documenso:3000 on the proxy network.
• The file reads every value from .env with ${VAR:?err}. Here the required ones from the Docker Compose page are written under environment: the database user and name documenso, NEXT_PUBLIC_WEBAPP_URL https://documenso.example.org, and the database URL with the generated password. NEXTAUTH_SECRET and both encryption keys are generated (the page generates them with openssl rand). The optional variables the file passes through empty (Google sign-in, S3 uploads, other mail transports, signup switches) are left out, so their defaults apply.
• The SMTP settings use the page's smtp-auth transport and come from .env, where you fill them in. NEXT_PRIVATE_SMTP_FROM_NAME is the page's example, Documenso.
• The signing certificate is ./cert.p12 next to this file instead of /opt/documenso/cert.p12 on the host, mounted read-only at the same path in the container; NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH is the file's default for it.

Notes for Documenso behind the proxy

• Before the first start, create the signing certificate with the Local Certificate page's commands, in the folder that holds this compose file, and give it the password you put in SIGNING_PASSPHRASE:
• $ openssl genrsa -out private.key 2048
• $ openssl req -new -x509 -key private.key -out certificate.crt -days 365
• $ openssl pkcs12 -export -out certificate.p12 -inkey private.key -in certificate.crt
• Then move it into place for the container user (UID 1001, as the Docker Compose page says) and delete the intermediate files: mv certificate.p12 ./documenso/cert.p12, sudo chown 1001:1001 ./documenso/cert.p12, chmod 400 ./documenso/cert.p12, rm private.key certificate.crt. A self-signed certificate signs documents, but PDF readers show it as untrusted; the docs point to a CA or an HSM for that.
• Open https://documenso.example.org, sign up and confirm your email address. Every account made this way is a regular user: the docs say admin rights are granted in the database. Once your accounts exist, set NEXT_PUBLIC_DISABLE_SIGNUP=true under documenso's environment and run docker compose up -d, or anyone who finds the address can sign up.
• Neither service has a restart policy in the file, so after a reboot Documenso stays down until docker compose up -d. Add restart: unless-stopped to both if you want it back by itself.
• The tag is latest; the Upgrades page recommends a version tag such as 1.5.0 for production.

Back it up

Documenso's backup page: the PostgreSQL database holds users, documents, signatures and audit logs, and here the PDFs too (database storage). The signing certificate is "critical. If lost, you cannot sign new documents until a new certificate is configured."

Below is the BACKUP.md the builder writes next to the compose file above: 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. Pick more apps in the builder and it covers them all in one file.

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

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)

## Documenso

Documenso's backup page: the PostgreSQL database holds users, documents, signatures and audit logs, and here the PDFs too (database storage). The signing certificate is "critical. If lost, you cannot sign new documents until a new certificate is configured."

What this compose mounts:
- documenso-database (named volume, /var/lib/postgresql/data in documenso-database)
  COVERED BY THE COMMAND BELOW: PostgreSQL's data files: accounts, documents and their PDFs, signatures, audit logs, templates. The pg_dump below is the copy to keep.
- ./documenso/cert.p12 (/opt/documenso/cert.p12 in documenso)
  BACK UP: the signing certificate. Keep it, and its password, somewhere safe and separate.

1. Database dump for documenso-database:

    docker compose exec -T documenso-database pg_dump -U documenso -F c documenso > "$BACKUP/documenso_backup.dump"

   The backup page's Docker Compose command, with this file's service name: a custom-format dump (-F c), compressed.

2. Copy (Documenso 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/documenso-cert.p12.tar.gz" ./documenso/cert.p12

Restore check:

    test -s "$BACKUP/documenso_backup.dump" && head -c 5 "$BACKUP/documenso_backup.dump" | grep -q PGDMP && echo OK   # a custom-format dump starts with PGDMP
    tar tzf "$BACKUP/documenso-cert.p12.tar.gz" > /dev/null && echo OK

Put a copy back (with Documenso stopped):

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

A custom-format dump goes back with pg_restore, into a fresh database before Documenso starts against it:

    docker compose up -d documenso-database
    docker compose exec -T documenso-database pg_restore -U documenso -d documenso --clean --if-exists < "$BACKUP/documenso_backup.dump"

Put ./documenso/cert.p12 back, then:

    docker compose up -d

Sources:
- Documenso docs: Backups (database, signing certificate): https://docs.documenso.com/docs/self-hosting/maintenance/backups (checked 2026-10-08)
- 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-08)

Update it

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

What Documenso's docs say about updating

Documenso's Upgrades page: back up first and read the release notes. Then, from the folder holding the compose file:

docker compose pull
docker compose up -d
docker compose logs -f documenso

• Database migrations run when the new version starts. The tag here is latest; the page recommends pinning a version tag such as documenso/documenso:1.5.0 in production and changing it on purpose.

Source: Documenso docs: Upgrades (image tags, pull, up -d, verify) checked 2026-10-08

The steps

1. Back up first, as in Back it up above. An update can migrate Documenso'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 Documenso start (Ctrl+C stops following the log, not the app):

   docker compose logs -f documenso

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

Locked out? Reset the admin password

Documenso sends a password reset email over the SMTP server this compose file requires; its docs give no command reset.

1. Check that the SMTP lines in .env are filled in: the Requirements page lists password resets among the emails Documenso sends, and the Email page lists the forgot-password and reset-password emails. Source: Documenso docs: Requirements (hardware; email for signing requests and password resets) read 2026-10-08; Documenso docs: Email (SMTP transports; forgot-password and reset-password emails) read 2026-10-08
2. Use the forgot-password link on the sign-in page and follow the email. If it never arrives, the Docker Compose page says to look for SMTP errors in the log: Source: Documenso docs: Docker Compose (required variables, signing certificate, first account) read 2026-10-08; Docker docs: docker compose logs read 2026-10-03

   docker compose logs documenso

Run the commands in the folder that holds docker-compose.yml.

Sources

Every page below was fetched on the date shown.

• Documenso on GitHub (repository description) checked 2026-10-08 (what it does)
• Documenso docs: Requirements (hardware; email for signing requests and password resets) checked 2026-10-08 (hardware requirements, compose definition and proxy settings)
• Documenso: docker/production/compose.yml (database, documenso) checked 2026-10-08 (compose definition and proxy settings)
• Documenso docs: Docker Compose (required variables, signing certificate, first account) checked 2026-10-08 (compose definition and proxy settings)
• Documenso docs: Local Certificate (generating a .p12 with OpenSSL) checked 2026-10-08 (compose definition and proxy settings)
• Documenso docs: Email (SMTP transports; forgot-password and reset-password emails) checked 2026-10-08 (compose definition and proxy settings)
• Documenso docs: Backups (database, signing certificate) checked 2026-10-08 (compose definition and proxy settings, backup plan)
• Documenso docs: Upgrades (image tags, pull, up -d, verify) checked 2026-10-08 (compose definition and proxy settings, update notes)
• Caddy docs: Keep Caddy running (Docker Compose section) checked 2026-09-23 (Caddy)
• Vaultwarden wiki: Caddy with HTTP challenge (uses the caddy:2 image) checked 2026-09-23 (Caddy)
• Docker docs: Volumes, Back up, restore, or migrate data volumes checked 2026-10-08 (backup plan)
• Caddy docs: Conventions, Data directory checked 2026-09-24 (backup plan)
• PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30 (database upgrade)
• Docker docs: docker compose pull checked 2026-09-30 (update steps)
• Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30 (update steps)
• Docker docs: docker image prune checked 2026-09-30 (update steps)

Add Documenso to the builder All one hundred apps