# Konfiguration

> Alle Einstellungen der Datei .env einer selbst gehosteten Docsello-Installation.

Docsello wird über die Datei `.env` neben der `docker-compose.yml` konfiguriert. Als Vorlage dient `.env.example`.
Nach einer Änderung startest du die Dienste neu: `docker compose up -d`.

## Pflicht

| Variable | Bedeutung |
|---|---|
| `APP_URL` | Öffentliche Adresse der Anwendung (Verwaltung, API, Anmeldung), z. B. `https://app.docs.example.com` |
| `ROOT_DOMAIN` | Workspaces liegen unter `<workspace>.<ROOT_DOMAIN>`, z. B. `docs.example.com` → `acme.docs.example.com`. Ohne Port |
| `APP_SECRET` | Mindestens 32 Zeichen (`openssl rand -hex 32`). Signiert Sitzungen, Freigabe-Links und Vorschauen – **nie mehr ändern**, sonst sind alle abgemeldet und Links ungültig |
| `POSTGRES_PASSWORD` | Datenbank-Passwort, nur Buchstaben und Ziffern (`openssl rand -hex 24`) |
| `APP_HOST` | Nur mit Caddy: Hostname von `APP_URL` |
| `ACME_EMAIL` | Nur mit Caddy: E-Mail-Adresse für Let's Encrypt |

`DATABASE_URL` und `STORAGE_DIR` setzt die `docker-compose.yml` selbst. Setze sie nur, wenn du ohne Compose oder mit
einer externen Datenbank arbeitest.

## E-Mail

| Variable | Bedeutung |
|---|---|
| `SMTP_URL` | z. B. `smtp://benutzer:passwort@smtp.example.com:587` – für Anmeldelinks, Passwort-Zurücksetzen und Einladungen. Ohne landen Mails nur im Log |
| `MAIL_FROM` | Absender, z. B. `Docsello <docs@example.com>` |

## Betrieb

| Variable | Standard | Bedeutung |
|---|---|---|
| `DOCSELLO_EDITION` | `selfhosted` | `selfhosted` = alle Funktionen frei; `cloud` für gehostete Angebote mit fremden Workspaces |
| `DOCSELLO_VERSION` | `latest` | Image-Version; fest eintragen (z. B. `0.1.4`) für kontrollierte Updates |
| `DOCSELLO_OPEN_SIGNUP` | aus | `1` = jeder darf sich registrieren und Workspaces anlegen. Sonst nur das erste Konto |
| `DEFAULT_SITE_ID` | älteste Website | Welche Website auf der Adresse von `APP_URL` selbst angezeigt wird |
| `DB_POOL` | `10` | Datenbankverbindungen pro Prozess |
| `WORKER_IDLE_MS` | `400` | Abfrage-Intervall des Workers bei leerer Warteschlange (ms) |
| `DOCSELLO_MAX_UPLOAD_MB` | `25` | Maximale Upload-Größe |

## Domains

| Variable | Bedeutung |
|---|---|
| `CNAME_TARGET` | Ziel, auf das eigene Domains per CNAME zeigen sollen (Standard: `ROOT_DOMAIN` ohne Port) |
| `TLS_ASK_TOKEN` | Optionales gemeinsames Geheimnis für Caddys Zertifikats-Abfrage (`/api/internal/tls-ask`) |
| `DOCSELLO_DOMAIN_REQUIRE_TXT` | `1` = eigene Domains brauchen den TXT-Eintrag `_docsello.<domain>` zur Prüfung. Sonst genügt ein CNAME bzw. A-Eintrag auf diesen Server |

## Screenshots und externe Adressen

| Variable | Bedeutung |
|---|---|
| `CAPTURE_BLOCK_PRIVATE` | `1` = Screenshots dürfen keine privaten Adressen (localhost, LAN) öffnen. Standardmäßig erlaubt, damit interne Anwendungen aufgenommen werden können |
| `CAPTURE_ALLOWED_HOSTS` | Kommagetrennte Liste von Hosts, die Screenshots öffnen dürfen (inkl. Subdomains). Leer = alle |
| `DOCSELLO_ALLOW_PRIVATE_URLS` | `1` = Webhooks, OpenAPI-URLs und andere Abrufe dürfen auch private Adressen erreichen |

## Updates

| Variable | Bedeutung |
|---|---|
| `UPDATE_SERVER_URL` | Update-Server, Standard `https://updates.cyrellian.com/docsello`. `off` schaltet die Prüfung ab |
| `UPDATE_CHANNEL` | `stable` (Standard) oder `beta` |
| `UPDATER_TOKEN`, `APP_DIR`, `UPDATER_URL` | Für den optionalen Updater-Container, siehe [Updates](doc:updates) |

:::warning[Fremde Workspaces hosten?]
Mit `DOCSELLO_EDITION=cloud` können Workspace-Admins eigenes JavaScript auf ihrer Website ausführen (HTML im
`<head>`, Modul *Eigenes HTML*). Lege `ROOT_DOMAIN` dann auf eine **andere registrierbare Domain** als `APP_URL`
(z. B. Verwaltung auf `docsello.com`, Websites auf `*.docsello.site`).
:::