---
title: "Documenso mit Docker installieren: Open-Source-Alternative zu DocuSign selbst hosten"
date: 2026-07-05T07:16:10+02:00
modified: 2026-11-10T17:48:22+01:00
category: cloud
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/documenso-docker-dokumentensignatur
reading_time: 12
personalize_url: "https://s-edv.com/anleitungen/documenso-docker-dokumentensignatur#domain={domain}"
variables:
  - name: mein_sicheres_zertpasswort
    label: "Mein sicheres zertpasswort"
    generated_in_browser: true
  - name: postgres_password
    label: "Passwort (postgres password)"
    generated_in_browser: true
  - name: nextauth_secret
    label: "Schlüssel (nextauth secret)"
    generated_in_browser: true
  - name: next_private_encryption_key
    label: "Schlüssel (next private encryption key)"
    generated_in_browser: true
  - name: ihr_secondary_key_hier
    label: "Ihr secondary key hier"
    generated_in_browser: true
  - name: domain
    label: "Ihre Domain"
    default: "example.com"
  - name: next_private_smtp_password
    label: "Next private smtp password"
    default: "IHR_SMTP_PASSWORT"
---

# Documenso mit Docker installieren: Open-Source-Alternative zu DocuSign selbst hosten

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{mein_sicheres_zertpasswort}}` | Mein sicheres zertpasswort | wird im Browser des Lesers zufällig erzeugt |
| `{{postgres_password}}` | Passwort (postgres password) | wird im Browser des Lesers zufällig erzeugt |
| `{{nextauth_secret}}` | Schlüssel (nextauth secret) | wird im Browser des Lesers zufällig erzeugt |
| `{{next_private_encryption_key}}` | Schlüssel (next private encryption key) | wird im Browser des Lesers zufällig erzeugt |
| `{{ihr_secondary_key_hier}}` | Ihr secondary key hier | wird im Browser des Lesers zufällig erzeugt |
| `{{domain}}` | Ihre Domain | `example.com` |
| `{{next_private_smtp_password}}` | Next private smtp password | `IHR_SMTP_PASSWORT` |

Link mit eigenen Werten: https://s-edv.com/anleitungen/documenso-docker-dokumentensignatur#domain=cloud.example.com

Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server. Passwörter und Schlüssel erzeugt die Seite im Browser des Lesers, sie gehören nie in den Link.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben.

Wer rechtssichere digitale Signaturen braucht, greift meist zu DocuSign oder Adobe Acrobat Sign und sendet dabei unweigerlich sensible Verträge in US-amerikanische Rechenzentren. Documenso schließt diese Lücke: Das Projekt (AGPL-3.0, über 13.000 GitHub-Sterne, aktuelle Version v2.21.0) bietet digitale Dokumentensignaturen nach dem EU-Standard PAdES auf dem eigenen Server. Für KMU, Rechtsabteilungen, Steuerkanzleien und HR-Teams bedeutet das: keine Abhängigkeit von US-Anbietern, volle DSGVO-Kontrolle und ein Audit-Trail, der auf der eigenen Infrastruktur liegt. Diese Anleitung führt Sie Schritt für Schritt durch die Docker-Compose-Installation, von der Ordnerstruktur über das Signaturzertifikat bis zur ersten Einladung an Unterzeichner.

**Kurzfassung:** Documenso läuft als Docker-Compose-Stack aus zwei Containern (App + PostgreSQL). Sie legen einen Projektordner an, erzeugen drei starke Secrets und ein PKCS#12-Signaturzertifikat mit OpenSSL, tragen alles in eine `.env` ein und starten mit `docker compose up -d`. Migrationen laufen automatisch beim ersten Start. Anschließend richten Sie im Browser den ersten Admin-Account ein und hängen einen Reverse Proxy für HTTPS davor. Für den Produktivbetrieb gilt: immer versionierten Image-Tag verwenden, nie `:latest`, und vor Updates ein Datenbank-Backup anlegen.

## Voraussetzungen

- [ ] **Docker Engine 20.10+** und **Docker Compose v2.0+** auf dem Host installiert; falls noch nicht geschehen, hilft die Anleitung [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage).
- [ ] Linux-Host, VM oder NAS mit mindestens 2 GB RAM, 2 CPU-Kernen und 20 GB freiem Speicher (Minimum: 1 GB RAM, 1 Kern, 10 GB).
- [ ] Eigene Domain mit DNS-A-Record auf den Server und ein TLS-Zertifikat, am einfachsten über Traefik oder Caddy mit automatischem Let's-Encrypt-Support. Für HTTPS ohne eigenen Reverse Proxy gilt die Anleitung [Caddy als Reverse Proxy einrichten](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung).
- [ ] **OpenSSL** auf dem Host (für Secret- und Zertifikatgenerierung).
- [ ] SMTP-Zugangsdaten eines E-Mail-Providers (z. B. Resend, Mailgun, eigener Postfix); ohne funktionierenden Mail-Versand können keine Signaturanfragen verschickt werden.
- [ ] Root- oder sudo-Zugang zum Host (für Verzeichnis- und Berechtigungsoperationen).

| Eigenschaft | Wert |
| --- | --- |
| Docker-Image | documenso/documenso:v2.21.0 (Docker Hub) · ghcr.io/documenso/documenso:v2.21.0 (GHCR) |
| Image-Größe | ca. 644 MB |
| Web-Port | 3000 (konfigurierbar über `PORT`) |
| Datenbank | PostgreSQL 14+ (ausschließlich; kein MySQL/SQLite) |
| Signaturstandard | PAdES (PDF Advanced Electronic Signatures, EU-konform) |
| Lizenz | AGPL-3.0 |
| RAM (Produktion) | mind. 2 GB (Minimum: 1 GB) |

## Schritt 1: Projektordner und Zertifikatsverzeichnis anlegen

Legen Sie zunächst die Ordnerstruktur auf dem Host an. Der Pfad `/opt/documenso` ist der dokumentierte Standard-Mountpunkt für das Signaturzertifikat im Container:

```bash
$ sudo mkdir -p /opt/documenso
$ cd /opt/documenso
```

Setzen Sie die Berechtigungen so, dass Ihr Admin-Benutzer die Dateien anlegen kann, der Container aber nur Lese-Zugriff auf das spätere Zertifikat bekommt:

```bash
$ sudo chown $(whoami):$(whoami) /opt/documenso
```

> **Prüfen:** `ls -la /opt/ | grep documenso`: Das Verzeichnis muss mit Ihrem Benutzer als Eigentümer existieren.

## Schritt 2: Signaturzertifikat (.p12) erstellen

Documenso benötigt ein PKCS#12-Zertifikat für PAdES-Signaturen. Das Image enthält kein Standard-Zertifikat, Sie müssen es selbst bereitstellen. Für interne Tests oder KMU-Einsatz ohne Anforderung an qualifizierte elektronische Signaturen (QES) reicht ein selbstsigniertes Zertifikat:

```bash
# Schlüssel und selbstsigniertes Zertifikat erzeugen (10 Jahre Laufzeit)
openssl req -x509 -nodes -newkey rsa:4096 \
  -keyout /opt/documenso/key.pem \
  -out /opt/documenso/cert.pem \
  -days 3650 \
  -subj "/CN=Documenso Signing/O=Mein Unternehmen/C=DE"

# PKCS#12-Bundle MIT Passwort erstellen (Pflicht, ohne Passwort schlägt Documenso fehl)
openssl pkcs12 -export \
  -out /opt/documenso/cert.p12 \
  -inkey /opt/documenso/key.pem \
  -in /opt/documenso/cert.pem \
  -passout pass:{{mein_sicheres_zertpasswort}}

# Zwischendateien entfernen, Berechtigungen setzen
rm /opt/documenso/key.pem /opt/documenso/cert.pem
sudo chown 1001:1001 /opt/documenso/cert.p12
sudo chmod 400 /opt/documenso/cert.p12
```

Notieren Sie sich das gewählte Passwort, es kommt in Schritt 3 als `NEXT_PRIVATE_SIGNING_PASSPHRASE` in die `.env`. Für rechtssichere qualifizierte Signaturen (QES) nach eIDAS benötigen Sie ein Zertifikat einer akkreditierten Vertrauensstelle (z. B. D-Trust, Bundesdruckerei).

> **Prüfen:** `ls -la /opt/documenso/cert.p12`: Die Ausgabe muss `-r--------` (400) mit Eigentümer `1001` zeigen. Mit `openssl pkcs12 -info -in /opt/documenso/cert.p12 -passin pass:{{mein_sicheres_zertpasswort}} -nokeys 2>/dev/null | head -5` können Sie das Zertifikat inhaltlich prüfen.

## Schritt 3: Secrets generieren und .env anlegen

Erzeugen Sie zunächst alle benötigten Zufalls-Secrets mit OpenSSL auf der Kommandozeile. Drei unabhängige Secrets mit je mindestens 32 Zeichen sind Pflicht:

```bash
$ openssl rand -base64 32  # NEXTAUTH_SECRET
$ openssl rand -base64 32  # NEXT_PRIVATE_ENCRYPTION_KEY
$ openssl rand -base64 32  # NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY
$ openssl rand -base64 24  # POSTGRES_PASSWORD
```

Legen Sie anschließend die Datei `/opt/documenso/.env` an und füllen Sie sie mit Ihren Werten:

Datei: `/opt/documenso/.env`

```ini
# ── Datenbank ────────────────────────────────────────────────
POSTGRES_USER=documenso
POSTGRES_PASSWORD={{postgres_password}}
POSTGRES_DB=documenso
NEXT_PRIVATE_DATABASE_URL=postgresql://documenso:{{postgres_password}}@database:5432/documenso

# ── Auth & Verschlüsselung ────────────────────────────────────
NEXTAUTH_SECRET={{nextauth_secret}}
NEXT_PRIVATE_ENCRYPTION_KEY={{next_private_encryption_key}}
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY={{ihr_secondary_key_hier}}

# ── URLs (exakt wie im Browser erreichbar) ───────────────────
NEXT_PUBLIC_WEBAPP_URL=https://sign.{{domain}}
NEXT_PRIVATE_INTERNAL_WEBAPP_URL=http://localhost:3000

# ── E-Mail ────────────────────────────────────────────────────
NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
NEXT_PRIVATE_SMTP_HOST=smtp.{{domain}}
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=absender@{{domain}}
NEXT_PRIVATE_SMTP_PASSWORD={{next_private_smtp_password}}
NEXT_PRIVATE_SMTP_FROM_ADDRESS=absender@{{domain}}
NEXT_PRIVATE_SMTP_FROM_NAME=Documenso

# ── Signaturzertifikat ────────────────────────────────────────
NEXT_PRIVATE_SIGNING_PASSPHRASE={{mein_sicheres_zertpasswort}}

# ── Optional: Telemetrie deaktivieren ─────────────────────────
DOCUMENSO_DISABLE_TELEMETRY=true

# ── Optional: Registrierung nach Erst-Setup sperren ──────────
# NEXT_PUBLIC_DISABLE_SIGNUP=true
```

Schützen Sie die Datei vor fremdem Zugriff:

```bash
$ chmod 600 /opt/documenso/.env
```

> **Prüfen:** `ls -la /opt/documenso/.env` muss `-rw-------` (600) anzeigen. Prüfen Sie kritische Werte: `grep NEXT_PRIVATE_DATABASE_URL /opt/documenso/.env`: Der Hostname muss `database` lauten (Docker-Compose-Servicename), niemals `localhost`.

## Schritt 4: compose.yaml anlegen

Erstellen Sie die Compose-Datei unter `/opt/documenso/compose.yaml`. Der `healthcheck` beim Datenbank-Service ist wichtig: Documenso wartet damit auf eine tatsächlich startbereite PostgreSQL-Instanz, bevor es mit Migrationen beginnt.

Datei: `/opt/documenso/compose.yaml`

```yaml
name: documenso

services:
  database:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - database:/var/lib/postgresql/data

  documenso:
    image: documenso/documenso:v2.21.0
    restart: unless-stopped
    depends_on:
      database:
        condition: service_healthy
    ports:
      - "${PORT:-3000}:${PORT:-3000}"
    environment:
      PORT: ${PORT:-3000}
      # Datenbank
      NEXT_PRIVATE_DATABASE_URL: ${NEXT_PRIVATE_DATABASE_URL}
      # Pflicht für die Migrationen beim Start (ohne PgBouncer identisch mit der URL oben)
      NEXT_PRIVATE_DIRECT_DATABASE_URL: ${NEXT_PRIVATE_DIRECT_DATABASE_URL:-${NEXT_PRIVATE_DATABASE_URL}}
      # Auth & Verschlüsselung
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXT_PRIVATE_ENCRYPTION_KEY: ${NEXT_PRIVATE_ENCRYPTION_KEY}
      NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY: ${NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY}
      # URLs
      NEXT_PUBLIC_WEBAPP_URL: ${NEXT_PUBLIC_WEBAPP_URL}
      NEXT_PRIVATE_INTERNAL_WEBAPP_URL: ${NEXT_PRIVATE_INTERNAL_WEBAPP_URL:-http://localhost:3000}
      # E-Mail
      NEXT_PRIVATE_SMTP_TRANSPORT: ${NEXT_PRIVATE_SMTP_TRANSPORT:-smtp-auth}
      NEXT_PRIVATE_SMTP_HOST: ${NEXT_PRIVATE_SMTP_HOST}
      NEXT_PRIVATE_SMTP_PORT: ${NEXT_PRIVATE_SMTP_PORT:-587}
      NEXT_PRIVATE_SMTP_USERNAME: ${NEXT_PRIVATE_SMTP_USERNAME}
      NEXT_PRIVATE_SMTP_PASSWORD: ${NEXT_PRIVATE_SMTP_PASSWORD}
      NEXT_PRIVATE_SMTP_FROM_ADDRESS: ${NEXT_PRIVATE_SMTP_FROM_ADDRESS}
      NEXT_PRIVATE_SMTP_FROM_NAME: ${NEXT_PRIVATE_SMTP_FROM_NAME:-Documenso}
      # Signaturzertifikat
      NEXT_PRIVATE_SIGNING_PASSPHRASE: ${NEXT_PRIVATE_SIGNING_PASSPHRASE}
      NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH: /opt/documenso/cert.p12
      # Telemetrie
      DOCUMENSO_DISABLE_TELEMETRY: "true"
    volumes:
      - /opt/documenso/cert.p12:/opt/documenso/cert.p12:ro

volumes:
  database:
```

Zwei Zeilen sind gegenüber älteren Vorlagen entscheidend: `NEXT_PRIVATE_DIRECT_DATABASE_URL` verlangt das Prisma-Schema für die Migrationen; fehlt sie, bricht die Migration beim Start ab und Documenso läuft danach in einer Neustartschleife mit „The table public.User does not exist“. Die offizielle Compose-Datei setzt sie deshalb standardmäßig auf `NEXT_PRIVATE_DATABASE_URL`. `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` teilt der Anwendung den Pfad des Zertifikats mit. Das Startskript findet die Datei zwar auch ohne diese Variable unter dem Standardpfad, die Signierfunktion selbst liest sie aber nur über die Variable; ohne sie meldet `/api/certificate-status` `"isAvailable":false`.

> **Prüfen:** `docker compose -f /opt/documenso/compose.yaml config`: Compose analysiert die Datei und zeigt die aufgelöste Konfiguration ohne Fehler an. Fehlende Pflicht-Variablen werden direkt als Fehler gemeldet.

## Schritt 5: Stack starten und Migrationen abwarten

Starten Sie den Stack aus dem Projektordner heraus:

```bash
$ cd /opt/documenso
$ docker compose up -d
```

Beim ersten Start führt Documenso automatisch alle Datenbankmigrationen aus, das kann zwei bis drei Minuten dauern. Beobachten Sie den Fortschritt live:

```bash
$ docker compose logs -f documenso
```

Sie warten auf die Zeile `All migrations have been successfully applied.`, danach startet der Server und meldet unter anderem `[JOBS]: Started cron poller`. Ab dann ist die App bereit.

> **Prüfen:** ```bash
> $ docker compose ps
> ```

Erwartete Ausgabe (beide Container müssen laufen):

Ausgabe:

```plaintext
NAME                   IMAGE                           STATUS
documenso-database-1   postgres:15                     Up X minutes (healthy)
documenso-documenso-1  documenso/documenso:v2.21.0     Up X minutes
```

Anschließend Health-Check-Endpunkt prüfen:

```bash
$ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/health
```

Erwartete Antwort: `200`. Der Endpunkt liefert seit den aktuellen Versionen zusätzlich ein JSON mit den Einzelprüfungen; `"status":"ok"` bedeutet, dass Datenbank und Zertifikat in Ordnung sind, `"warning"` deutet meist auf ein nicht geladenes Zertifikat hin. Den Zertifikat-Status prüfen Sie mit:

```bash
$ curl -s http://localhost:3000/api/certificate-status
```

Erwartete Antwort: `{"isAvailable":true,...}`.

## Schritt 6: Reverse Proxy und HTTPS einrichten

Für den Produktivbetrieb ist HTTPS Pflicht: `NEXT_PUBLIC_WEBAPP_URL` muss die `https://`-URL enthalten, sonst funktionieren Token-Links in E-Mails und OAuth-Callbacks nicht. Richten Sie einen Reverse Proxy vor Documenso (Port 3000) ein. Empfohlen:

1. **Traefik**: Labels am Documenso-Service ergänzen, Traefik übernimmt Let's-Encrypt-Zertifikate automatisch. Anleitung: [Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten).
2. **Caddy**: Eintrag in der Caddyfile: `sign.{{domain}} { reverse_proxy documenso:3000 }`. Anleitung: [Caddy als Reverse Proxy einrichten](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung).
3. **Nginx Proxy Manager**: Proxy-Host für Port 3000 anlegen, SSL via Let's Encrypt aktivieren.

Wichtig: Setzen Sie in der `.env` nach dem DNS-Eintrag und dem Reverse-Proxy-Setup die korrekte öffentliche URL und die interne URL für Hintergrund-Jobs:

Datei: `.env`

```ini
NEXT_PUBLIC_WEBAPP_URL=https://sign.{{domain}}
NEXT_PRIVATE_INTERNAL_WEBAPP_URL=http://localhost:3000
```

Die interne URL muss auf `localhost:3000` zeigen (nicht auf die öffentliche Domain), damit Hintergrund-Jobs den Reverse Proxy umgehen. Starten Sie den Stack nach der Änderung neu:

```bash
$ docker compose up -d --force-recreate documenso
```

> **Prüfen:** Rufen Sie `https://sign.{{domain}}` im Browser auf; Sie sollten die Documenso-Startseite mit gültigem TLS-Zertifikat sehen. `curl -I https://sign.{{domain}}/api/health` gibt HTTP 200 zurück.

## Schritt 7: Erst-Einrichtung im Browser und Registrierung sperren

Öffnen Sie `https://sign.{{domain}}` und erstellen Sie den ersten Admin-Account über das Registrierungsformular. Sichern Sie Passwort und E-Mail-Adresse sorgfältig, über diesen Account verwalten Sie später alle Teams und Einstellungen.

Nach dem ersten Login empfiehlt es sich, weitere Registrierungen zu sperren, wenn Sie Documenso nur für Ihr Team nutzen wollen. Ergänzen Sie in der `.env`:

Datei: `.env`

```ini
NEXT_PUBLIC_DISABLE_SIGNUP=true
```

Alternativ schränken Sie die Registrierung auf bestimmte E-Mail-Domains ein:

```ini
NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS=ihrunternehmen.de,partner.de
```

Container neu starten, damit die Änderung wirksam wird:

```bash
$ docker compose up -d --force-recreate documenso
```

> **Prüfen:** Melden Sie sich als Admin an und rufen Sie `https://sign.{{domain}}/api/certificate-status` im Browser auf. Die Antwort zeigt, ob das Signaturzertifikat korrekt geladen ist. Laden Sie ein Test-PDF hoch, fügen Sie sich als Unterzeichner hinzu und prüfen Sie, ob die Einladungsmail eintrifft.

## Schritt 8: Updates und Datenbank-Backup

Documenso erscheint regelmäßig mit neuen Versionen. Prüfen Sie vor jedem Update die Release-Notes auf Breaking Changes. Erstellen Sie immer zuerst ein Datenbank-Backup:

```bash
# Backup erstellen
```

```bash
$ docker compose exec database pg_dump -U documenso documenso > /opt/documenso/backup_$(date +%Y%m%d).sql
```

```bash
# Image-Tag in compose.yaml auf neue Version anpassen, dann:
```

```bash
$ docker compose pull
$ docker compose up -d
```

**Update von v2.19 auf v2.21:** Seit v2.20 prüft Documenso bei jedem POST mit Sitzungs-Cookie, ob der `Origin`-Header exakt dem Ursprung aus `NEXT_PUBLIC_WEBAPP_URL` entspricht; sonst antwortet der Server mit `403 Forbidden` und protokolliert `csrf.origin_rejected`. Diese URL muss also genau der Browser-Adresse entsprechen, und der Reverse Proxy muss den `Origin`-Header unverändert weiterreichen. Beim Wechsel von v2.19.0 auf v2.21.0 spielt Documenso eine Migration ein, das Konto bleibt erhalten, die Anmeldung mit passendem Origin liefert `201`, ohne oder mit fremdem Origin `403`. Ältere Instanzen ab v2.11 brauchen zusätzlich die beiden Variablen aus Schritt 4: ohne `NEXT_PRIVATE_DIRECT_DATABASE_URL` scheitern die Migrationen, ohne `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` fehlt das Signaturzertifikat. Ein Zurückspielen der älteren Version ist nach den Migrationen nicht vorgesehen; halten Sie daher den Dump bereit.

Datenbankmigrationen laufen automatisch beim Neustart. Überwachen Sie den Fortschritt mit `docker compose logs -f documenso`. Für eine strukturierte Backup-Strategie empfiehlt sich die Anleitung zu [PostgreSQL pg_dump und pg_restore: Backup und Migration](https://s-edv.com/anleitungen/postgresql-pg-dump-pg-restore-backup-migration). Für automatische Update-Benachrichtigungen ohne blindes `:latest`-Pulling hilft die Anleitung zu [Docker-Container automatisch aktualisieren](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-wud).

> **Prüfen:** Nach dem Update `docker compose ps`: Beide Container müssen mit dem neuen Image-Tag und Status `Up` laufen. `curl -s http://localhost:3000/api/health` gibt weiterhin HTTP 200 zurück. Im Browser zeigt die neue Versionsnummer in den Einstellungen den Erfolg.

## Troubleshooting / Typische Fehler

**„Failed to get private key bags“**

Das `.p12`-Zertifikat wurde ohne Passwort erstellt. Lösung: Zertifikat neu erstellen und dabei `-passout pass:PASSWORT` übergeben; `NEXT_PRIVATE_SIGNING_PASSPHRASE` in der `.env` setzen.

**EACCES permission denied beim Signieren**

Der Container läuft als UID 1001 (non-root), hat aber keinen Lesezugriff auf `cert.p12`. Lösung: `sudo chown 1001:1001 /opt/documenso/cert.p12 && sudo chmod 400 /opt/documenso/cert.p12` auf dem Host ausführen.

**Signatur läuft durch, erzeugt aber keine gültige Unterschrift**

Kein Zertifikat konfiguriert, falsch gemountet oder `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` fehlt; Documenso startet problemlos auch ohne Zertifikat, und das Startskript meldet die Datei trotzdem als gefunden. Diagnose: `/api/certificate-status` aufrufen, erwartet ist `"isAvailable":true`.

**Neustartschleife mit „The table public.User does not exist“**

Im Log steht zuvor `Environment variable not found: NEXT_PRIVATE_DIRECT_DATABASE_URL`, die Migrationen sind nie gelaufen. Lösung: Variable wie in Schritt 4 ergänzen und den Container neu erstellen.

**Datenbankverbindung schlägt fehl, „connection refused“**

`NEXT_PRIVATE_DATABASE_URL` verwendet `localhost` statt dem Compose-Servicenamen. Lösung: URL-Hostname muss `database` lauten, also `postgresql://documenso:PASS@database:5432/documenso`.

**Token-Links in E-Mails sind falsch oder OAuth-Callback schlägt fehl**

`NEXT_PUBLIC_WEBAPP_URL` ist falsch gesetzt (z. B. `http://` statt `https://` oder fehlender Port). Lösung: URL exakt so setzen, wie sie im Browser erreichbar ist.

**Erster Start hängt oder läuft in Timeout**

Datenbankmigrationen beim Erststart benötigen Zeit. Lösung: `depends_on` mit `condition: service_healthy` in der Compose-Datei sicherstellen und `docker compose logs -f documenso` abwarten.

**Hintergrund-Jobs (E-Mail-Versand) schlagen fehl**

`NEXT_PRIVATE_INTERNAL_WEBAPP_URL` zeigt auf die öffentliche Domain statt auf `http://localhost:3000`. Lösung: Variable auf die interne Container-URL setzen.

**Anmeldung oder Speichern liefert „Forbidden“ (403)**

`Origin` passt nicht zu `NEXT_PUBLIC_WEBAPP_URL` (ab v2.20, Log: `csrf.origin_rejected`). Lösung: URL exakt auf die Browser-Adresse setzen.

**Breaking Changes nach Update**

Verwendung von `:latest`-Tag. Lösung: In der `compose.yaml` immer konkrete Versionstags wie `:v2.21.0` einsetzen und vor jedem Update die Release-Notes lesen.

## Häufige Fragen

### Benötige ich zwingend ein SSL-Zertifikat für den Betrieb?

Ja, für den Produktivbetrieb ist HTTPS Pflicht. HTTP reicht ausschließlich für lokale Tests. `NEXT_PUBLIC_WEBAPP_URL` muss die `https://`-URL enthalten, sonst funktionieren Token-Links in E-Mails, OAuth-Callbacks und viele sicherheitsrelevante Browser-Features nicht korrekt. Am einfachsten übernimmt ein vorgelagerter Reverse Proxy (Traefik, Caddy, Nginx) die TLS-Terminierung mit Let's-Encrypt-Zertifikaten.

### Wie erstelle ich ein Signaturzertifikat (.p12) für rechtssichere Signaturen?

Für interne Zwecke oder fortgeschrittene elektronische Signaturen reicht ein selbstsigniertes OpenSSL-Zertifikat wie in Schritt 2 beschrieben. Für qualifizierte elektronische Signaturen (QES) nach eIDAS (die höchste Rechtsstufe, gleichwertig mit handschriftlicher Unterschrift) benötigen Sie ein Zertifikat von einer akkreditierten Vertrauensstelle (z. B. D-Trust, Bundesdruckerei). Diese Zertifikate sind kostenpflichtig und erfordern eine Identitätsprüfung.

### Werden Dokumente in der Datenbank oder im Dateisystem gespeichert?

Standardmäßig in PostgreSQL (`NEXT_PUBLIC_UPLOAD_TRANSPORT=database`). Das ist für KMU mit moderatem Dokumentenaufkommen praktisch, da kein zusätzlicher Speicher-Service benötigt wird. Bei großen Dokumentenmengen empfiehlt sich S3-kompatible Speicherung (AWS S3, MinIO, Cloudflare R2) über die entsprechenden S3-Umgebungsvariablen.

### Kann ich die Benutzerregistrierung deaktivieren?

Ja: `NEXT_PUBLIC_DISABLE_SIGNUP=true` sperrt alle Neuregistrierungen vollständig. Mit `NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS=ihrunternehmen.de` erlauben Sie nur Registrierungen von bestimmten E-Mail-Domains. Bestehende Benutzerkonten sind von beiden Einstellungen nicht betroffen.

### Benötigt Documenso Redis?

Nein. Redis ist optional. Der Standard-Jobs-Provider `local` nutzt PostgreSQL für die interne Jobqueue, ohne externe Abhängigkeiten. Redis (BullMQ-Provider) oder Inngest empfehlen sich erst bei sehr hohem Durchsatz oder wenn Sie eine verwaltete Job-Infrastruktur bevorzugen.

### Kann ich Nicht-PDF-Dokumente (DOCX, ODT) hochladen?

Ja, wenn Sie einen Gotenberg-Container als zusätzlichen Service in den Stack einbinden und `NEXT_PRIVATE_DOCUMENT_CONVERSION_URL=http://gotenberg:3000` setzen. Gotenberg konvertiert DOCX, ODT und weitere Formate serverseitig zu PDF, bevor Documenso sie verarbeitet.

## Fazit

Documenso ist eine ausgereifte, aktiv gepflegte Alternative zu DocuSign, die sich mit überschaubarem Aufwand auf eigener Infrastruktur betreiben lässt. Der größte konzeptionelle Unterschied zu SaaS-Angeboten: Sie tragen die Verantwortung für Betrieb, Backups und Updates selbst. Das zahlt sich aus, wenn DSGVO-Compliance ohne US-Datenverarbeitung für Sie oder Ihre Kunden nicht verhandelbar ist. Die Pflicht-Komplexität liegt vor allem beim Signaturzertifikat (PKCS#12 mit Passwort) und der korrekten URL-Konfiguration, zwei Punkte, bei denen erfahrungsgemäß die meisten Fehler entstehen. Wer diese Stolpersteine kennt, hat eine zuverlässige, rechtssichere Signaturlösung auf dem eigenen Server, die mit dem Team wächst.

## Weiterführende Anleitungen und Quellen

1. [Docker Compose absichern](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)
2. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
3. [Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten)
4. [Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung)
5. [Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-wud)
6. [Paperless-ngx mit Docker einrichten: papierlose Dokumentenverwaltung mit OCR](https://s-edv.com/anleitungen/paperless-ngx-dokumentenverwaltung-ocr-docker)
7. [Stirling-PDF mit Docker: der lokale PDF-Werkzeugkasten](https://s-edv.com/anleitungen/stirling-pdf-werkzeugkasten-docker-einrichten)
8. [PostgreSQL pg_dump und pg_restore: Backup und Migration per Kommandozeile](https://s-edv.com/anleitungen/postgresql-pg-dump-pg-restore-backup-migration)

Offizielle Quellen: [Documenso Docs: Docker Compose Deployment](https://docs.documenso.com/docs/self-hosting/deployment/docker-compose) · [Environment Variables Reference](https://docs.documenso.com/docs/self-hosting/configuration/environment) · [Tips und Common Pitfalls](https://docs.documenso.com/docs/self-hosting/getting-started/tips) · [GitHub Repository](https://github.com/documenso/documenso)

## Passende Anleitungen auf S-EDV

1. [OpenSSL: Neun Schwachstellen im Sicherheitsrelease vom 9. Juni 2026, darunter Hi](https://s-edv.com/news/openssl-9-schwachstellen-juni-2026-patch-pkcs7)
2. [PostgreSQL schließt elf Sicherheitslücken in den Versionen 14 bis 18](https://s-edv.com/news/postgresql-11-sicherheitsluecken-versionen-14-18-mai-2026)
3. [netcup Local Block Storage bestellen, einrichten und unter Linux einbinden](https://s-edv.com/anleitungen/netcup-local-block-storage-bestellen-linux-einbinden)
