katalon-cli 0.1.20__tar.gz → 0.2.1__tar.gz

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: katalon-cli
-Version: 0.1.20
+Version: 0.2.1
 Summary: Installer & Updater CLI für Katalon Production-Instanzen
 Author: Karl Krägelin
 Author-email: Karl Krägelin <karlkraegelin@gmail.com>
@@ -33,7 +33,7 @@ katalon start / stop / status
 katalon check-updates         # prüft nur, ob ein neues Release verfügbar ist
 katalon update                # interaktives Update, Backup zuerst immer
 katalon rollback               # letztes Backup einspielen
-katalon doctor                 # Docker, Diskspace, Ports prüfen
+katalon doctor                 # Docker, Diskspace, Ports, Schreibrechte von MEDIA_ROOT prüfen
 katalon backup                 # manuelles Backup
 katalon logs [service]
 katalon manage <args>          # katalon-manage im api-Container (z.B. reset-admin, create-user)
@@ -66,6 +66,57 @@ katalon start
 katalon status
 ```
 
+## API-Adresse
+
+Die REST-API liegt direkt unter der Base-URL, ohne `/api`-Präfix: `<KATALON_BASE_URL>/v1/...`
+(z. B. Login unter `http://127.0.0.1:8080/v1/...` bei `behind-proxy`). Unter `/api/` liegen nur
+die OpenAPI-Dokumentation (`/api/docs`, `/api/openapi.json`) und interne Endpunkte;
+`/api/v1/...` liefert für normale API-Aufrufe 404.
+
+## Medienverzeichnis und Rechte
+
+API und Worker laufen im Container als unprivilegierter User (`USER` im Image). `MEDIA_ROOT`
+ist ein Bind-Mount vom Host und muss für diesen User beschreibbar sein. `katalon start`
+(auch beim Install), `update` und `rollback` lesen UID/GID per `id` aus dem api-Container und
+setzen in einem kurzlebigen root-Container desselben Images den Eigentümer aller Einträge
+unter `MEDIA_ROOT`, die noch einem anderen Eigentümer gehören. Dateiinhalte werden nicht
+verändert; ein erneuter Lauf ändert nichts. `katalon doctor` meldet ein nicht beschreibbares
+`MEDIA_ROOT`, bevor Uploads mit HTTP 500 scheitern.
+
+## Domain und HTTPS
+
+Für eine lokale Installation bleibt `http://localhost` mit TLS-Modus `none` der Standard.
+Bei einer öffentlichen Domain schlägt der Setup-Wizard `caddy` vor. Du kannst auch nur
+`sammlung.example.org` eingeben; mit Caddy wird daraus `https://sammlung.example.org`.
+
+Vor der Installation müssen die DNS-Einträge wirksam sein: Der A-Record zeigt auf die öffentliche
+IPv4-Adresse des Servers. Ein vorhandener AAAA-Record muss auf dessen erreichbare IPv6-Adresse
+zeigen. TCP-Ports 80 und 443 müssen frei und öffentlich erreichbar sein, auch durch Server- und
+Provider-Firewalls sowie gegebenenfalls Portweiterleitungen. Docker und Docker Compose müssen
+installiert sein. Die CLI prüft freie Ports lokal, aber keine öffentliche DNS-Auflösung oder
+Erreichbarkeit von außen.
+
+Die TLS-Modi:
+
+- `caddy`: Caddy läuft als Docker-Container vor dem internen nginx, belegt Ports 80 und 443,
+  beantragt öffentlich vertrauenswürdige Zertifikate und erneuert sie automatisch.
+  HTTP wird auf HTTPS umgeleitet. Zertifikate und Zustand liegen dauerhaft in den Docker-Volumes
+  `caddy_data` und `caddy_config`, die bei Neustarts, Updates und Rollbacks erhalten bleiben.
+  Dafür muss Caddy weiterlaufen, DNS muss stimmen und der Server erreichbar bleiben.
+- `standalone`: nginx verwendet ein selbstsigniertes Zertifikat. Browser zeigen eine Warnung;
+  es gibt keine automatische Erneuerung. Eigene Zertifikate können unter `<dir>/certs/`
+  als `fullchain.pem` und `privkey.pem` abgelegt werden. Ihre Erneuerung und das anschließende
+  Neuladen von nginx musst du selbst einrichten.
+- `behind-proxy`: Ein eigener Reverse-Proxy übernimmt HTTPS und Zertifikate.
+  Katalon ist standardmäßig nur auf `127.0.0.1:8080` erreichbar.
+- `none`: HTTP ohne TLS, für lokale Tests oder IP-Adressen.
+
+Die erste Zertifikatsausstellung kann nach dem Start kurz dauern. Bei HTTPS-Problemen:
+`katalon logs caddy`. Caddy-Konfiguration und Zertifikatsverwaltung sind in der
+[Caddy-Dokumentation](https://caddyserver.com/docs/automatic-https) beschrieben.
+Die CLI erzeugt `<dir>/Caddyfile` bei Installation, Update und Rollback neu;
+instanzspezifische Compose-Anpassungen gehören in `compose.override.yaml`.
+
 ## Entwicklung
 
 ```bash
@@ -83,7 +134,8 @@ uv run pytest
   nach (`--yes` bricht dann ab), tragen neue optionale Variablen auskommentiert in `.env` ein und
   warnen vor veralteten Variablen, die noch in der `.env` stehen.
 - `core/compose_gen.py` + `templates/compose.yaml.j2` + `templates/nginx.conf.j2` — rendert `compose.yaml`
-  + `nginx.conf` aus Version + TLS-Modus; erzeugt bei `tls_mode=standalone` ein selbstsigniertes
+  + `nginx.conf` und bei `tls_mode=caddy` das `Caddyfile` aus Version + TLS-Modus;
+  erzeugt bei `tls_mode=standalone` ein selbstsigniertes
   Zertifikat unter `<dir>/certs/` (eigenes Zertifikat dort ablegen, um es zu ersetzen).
   `install` fragt zusätzlich `MEDIA_ROOT` ab und legt `<dir>/compose.override.yaml.example` an
   (instanzspezifische Overrides — umbenennen zu `compose.override.yaml`, wird automatisch eingebunden

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/README.md

@@ -19,7 +19,7 @@ katalon start / stop / status
 katalon check-updates         # prüft nur, ob ein neues Release verfügbar ist
 katalon update                # interaktives Update, Backup zuerst immer
 katalon rollback               # letztes Backup einspielen
-katalon doctor                 # Docker, Diskspace, Ports prüfen
+katalon doctor                 # Docker, Diskspace, Ports, Schreibrechte von MEDIA_ROOT prüfen
 katalon backup                 # manuelles Backup
 katalon logs [service]
 katalon manage <args>          # katalon-manage im api-Container (z.B. reset-admin, create-user)
@@ -52,6 +52,57 @@ katalon start
 katalon status
 ```
 
+## API-Adresse
+
+Die REST-API liegt direkt unter der Base-URL, ohne `/api`-Präfix: `<KATALON_BASE_URL>/v1/...`
+(z. B. Login unter `http://127.0.0.1:8080/v1/...` bei `behind-proxy`). Unter `/api/` liegen nur
+die OpenAPI-Dokumentation (`/api/docs`, `/api/openapi.json`) und interne Endpunkte;
+`/api/v1/...` liefert für normale API-Aufrufe 404.
+
+## Medienverzeichnis und Rechte
+
+API und Worker laufen im Container als unprivilegierter User (`USER` im Image). `MEDIA_ROOT`
+ist ein Bind-Mount vom Host und muss für diesen User beschreibbar sein. `katalon start`
+(auch beim Install), `update` und `rollback` lesen UID/GID per `id` aus dem api-Container und
+setzen in einem kurzlebigen root-Container desselben Images den Eigentümer aller Einträge
+unter `MEDIA_ROOT`, die noch einem anderen Eigentümer gehören. Dateiinhalte werden nicht
+verändert; ein erneuter Lauf ändert nichts. `katalon doctor` meldet ein nicht beschreibbares
+`MEDIA_ROOT`, bevor Uploads mit HTTP 500 scheitern.
+
+## Domain und HTTPS
+
+Für eine lokale Installation bleibt `http://localhost` mit TLS-Modus `none` der Standard.
+Bei einer öffentlichen Domain schlägt der Setup-Wizard `caddy` vor. Du kannst auch nur
+`sammlung.example.org` eingeben; mit Caddy wird daraus `https://sammlung.example.org`.
+
+Vor der Installation müssen die DNS-Einträge wirksam sein: Der A-Record zeigt auf die öffentliche
+IPv4-Adresse des Servers. Ein vorhandener AAAA-Record muss auf dessen erreichbare IPv6-Adresse
+zeigen. TCP-Ports 80 und 443 müssen frei und öffentlich erreichbar sein, auch durch Server- und
+Provider-Firewalls sowie gegebenenfalls Portweiterleitungen. Docker und Docker Compose müssen
+installiert sein. Die CLI prüft freie Ports lokal, aber keine öffentliche DNS-Auflösung oder
+Erreichbarkeit von außen.
+
+Die TLS-Modi:
+
+- `caddy`: Caddy läuft als Docker-Container vor dem internen nginx, belegt Ports 80 und 443,
+  beantragt öffentlich vertrauenswürdige Zertifikate und erneuert sie automatisch.
+  HTTP wird auf HTTPS umgeleitet. Zertifikate und Zustand liegen dauerhaft in den Docker-Volumes
+  `caddy_data` und `caddy_config`, die bei Neustarts, Updates und Rollbacks erhalten bleiben.
+  Dafür muss Caddy weiterlaufen, DNS muss stimmen und der Server erreichbar bleiben.
+- `standalone`: nginx verwendet ein selbstsigniertes Zertifikat. Browser zeigen eine Warnung;
+  es gibt keine automatische Erneuerung. Eigene Zertifikate können unter `<dir>/certs/`
+  als `fullchain.pem` und `privkey.pem` abgelegt werden. Ihre Erneuerung und das anschließende
+  Neuladen von nginx musst du selbst einrichten.
+- `behind-proxy`: Ein eigener Reverse-Proxy übernimmt HTTPS und Zertifikate.
+  Katalon ist standardmäßig nur auf `127.0.0.1:8080` erreichbar.
+- `none`: HTTP ohne TLS, für lokale Tests oder IP-Adressen.
+
+Die erste Zertifikatsausstellung kann nach dem Start kurz dauern. Bei HTTPS-Problemen:
+`katalon logs caddy`. Caddy-Konfiguration und Zertifikatsverwaltung sind in der
+[Caddy-Dokumentation](https://caddyserver.com/docs/automatic-https) beschrieben.
+Die CLI erzeugt `<dir>/Caddyfile` bei Installation, Update und Rollback neu;
+instanzspezifische Compose-Anpassungen gehören in `compose.override.yaml`.
+
 ## Entwicklung
 
 ```bash
@@ -69,7 +120,8 @@ uv run pytest
   nach (`--yes` bricht dann ab), tragen neue optionale Variablen auskommentiert in `.env` ein und
   warnen vor veralteten Variablen, die noch in der `.env` stehen.
 - `core/compose_gen.py` + `templates/compose.yaml.j2` + `templates/nginx.conf.j2` — rendert `compose.yaml`
-  + `nginx.conf` aus Version + TLS-Modus; erzeugt bei `tls_mode=standalone` ein selbstsigniertes
+  + `nginx.conf` und bei `tls_mode=caddy` das `Caddyfile` aus Version + TLS-Modus;
+  erzeugt bei `tls_mode=standalone` ein selbstsigniertes
   Zertifikat unter `<dir>/certs/` (eigenes Zertifikat dort ablegen, um es zu ersetzen).
   `install` fragt zusätzlich `MEDIA_ROOT` ab und legt `<dir>/compose.override.yaml.example` an
   (instanzspezifische Overrides — umbenennen zu `compose.override.yaml`, wird automatisch eingebunden

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalon-cli"
-version = "0.1.20"
+version = "0.2.1"
 description = "Installer & Updater CLI für Katalon Production-Instanzen"
 readme = "README.md"
 requires-python = ">=3.12"

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "katalon-cli"
-version = "0.1.20"
+version = "0.2.1"
 description = "Installer & Updater CLI für Katalon Production-Instanzen"
 readme = "README.md"
 authors = [

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/src/katalon_cli/core/compose_gen.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import re
 import subprocess
+from ipaddress import ip_address
 from pathlib import Path
+from urllib.parse import urlparse
 
 from jinja2 import Environment, PackageLoader, select_autoescape
 
@@ -22,8 +25,8 @@ def render_compose(
     tls_mode: str,
     registry: str = "ghcr.io/katalon-collections/katalon",
 ) -> str:
-    from urllib.parse import urlparse
-
+    if tls_mode == "caddy":
+        caddy_host(base_url)
     parsed_port = urlparse(base_url).port
     template = _env.get_template("compose.yaml.j2")
     return template.render(
@@ -47,6 +50,10 @@ def write_compose(instance_dir: Path, **kwargs) -> Path:
     nginx_path = instance_dir / "nginx.conf"
     nginx_path.write_text(render_nginx_conf(tls_mode=kwargs["tls_mode"]))
 
+    if kwargs["tls_mode"] == "caddy":
+        template = _env.get_template("Caddyfile.j2")
+        (instance_dir / "Caddyfile").write_text(template.render(host=caddy_host(kwargs["base_url"])))
+
     if kwargs["tls_mode"] == "standalone":
         ensure_self_signed_cert(instance_dir, host=_host_of(kwargs["base_url"]))
 
@@ -79,7 +86,27 @@ def ensure_self_signed_cert(instance_dir: Path, *, host: str) -> None:
     )
 
 
-def _host_of(base_url: str) -> str:
-    from urllib.parse import urlparse
+def caddy_host(base_url: str) -> str:
+    """Validiert die öffentliche HTTPS-Adresse vor dem Rendern der Caddy-Konfiguration."""
+    parsed = urlparse(base_url)
+    host = (parsed.hostname or "").encode("idna").decode("ascii")
+    try:
+        ip_address(host)
+        is_ip = True
+    except ValueError:
+        is_ip = False
+    label = r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?"
+    if (
+        parsed.scheme != "https" or parsed.port not in (None, 443)
+        or parsed.username is not None or parsed.password is not None
+        or parsed.path not in ("", "/") or parsed.query or parsed.fragment
+        or is_ip or len(host) > 253
+        or not re.fullmatch(rf"{label}(?:\.{label})+", host)
+        or host.endswith((".localhost", ".local"))
+    ):
+        raise ValueError("Caddy benötigt eine öffentliche Domain als https://domain.tld ohne Pfad (Port 443).")
+    return host
 
+
+def _host_of(base_url: str) -> str:
     return urlparse(base_url).hostname or "localhost"

katalon_cli-0.2.1/src/katalon_cli/core/permissions.py

@@ -0,0 +1,113 @@
+"""Schreibrechte für Bind-Mounts, in die API und Worker schreiben.
+
+API- und Worker-Image laufen als unprivilegierter User (Dockerfile `USER`). Ein vom
+Installer oder per Hand angelegtes Host-Verzeichnis gehört dagegen meist root. Die
+UID/GID wird nicht im CLI hinterlegt, sondern zur Laufzeit aus dem Container gelesen
+(`id` im api-Service, inkl. eventuellem `user:` aus compose.override.yaml).
+
+Die Korrektur läuft als root in einem Wegwerf-Container desselben Images — dadurch
+funktioniert sie auch, wenn die CLI selbst nicht als root läuft. Sie ändert nur Eigentümer
+von Einträgen mit falschem Eigentümer, nie Inhalte, und ist damit idempotent.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import docker
+
+# Container-Pfad des MEDIA_ROOT-Bind-Mounts (compose.yaml.j2, api + worker).
+CONTAINER_MEDIA_ROOT = "/var/lib/katalon/media"
+# Services, die in CONTAINER_MEDIA_ROOT schreiben.
+WRITER_SERVICES = ("api", "worker")
+# Service, dessen Image-User als Eigentümer gesetzt wird.
+OWNER_SERVICE = "api"
+
+
+class PermissionFixError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class ContainerUser:
+    uid: int
+    gid: int
+    name: str = ""
+
+    def __str__(self) -> str:
+        label = f"{self.uid}:{self.gid}"
+        return f"{label} ({self.name})" if self.name else label
+
+
+_ID_RE = re.compile(r"uid=(\d+)(?:\(([^)]*)\))?\s+gid=(\d+)")
+
+
+def parse_id_output(output: str) -> ContainerUser:
+    match = _ID_RE.search(output)
+    if not match:
+        raise PermissionFixError(f"Unerwartete Ausgabe von `id`: {output.strip()!r}")
+    return ContainerUser(uid=int(match.group(1)), gid=int(match.group(3)), name=match.group(2) or "")
+
+
+def _run(instance_dir: Path, service: str, *args: str, root: bool = False):
+    user = ["--user", "0:0"] if root else []
+    return docker.compose(
+        instance_dir,
+        "run", "--rm", "--no-deps", "-T", *user, "--entrypoint", args[0], service, *args[1:],
+        check=False,
+        capture=True,
+    )
+
+
+def container_user(instance_dir: Path, service: str = OWNER_SERVICE) -> ContainerUser:
+    """UID/GID, unter der `service` tatsächlich läuft (Image-USER bzw. compose `user:`)."""
+    result = _run(instance_dir, service, "id")
+    if result.returncode != 0:
+        raise PermissionFixError(
+            f"UID des {service}-Containers nicht ermittelbar: {(result.stderr or result.stdout).strip()}"
+        )
+    return parse_id_output(result.stdout)
+
+
+def chown_args(path: str, user: ContainerUser) -> list[str]:
+    """`find`-Aufruf, der nur Einträge mit falschem Eigentümer umstellt (Inhalte bleiben unberührt)."""
+    owner = f"{user.uid}:{user.gid}"
+    return [
+        "find", path, "-xdev",
+        "(", "!", "-user", str(user.uid), "-o", "!", "-group", str(user.gid), ")",
+        "-exec", "chown", "-h", owner, "{}", "+",
+    ]
+
+
+def is_writable(instance_dir: Path, service: str) -> bool:
+    result = _run(instance_dir, service, "test", "-w", CONTAINER_MEDIA_ROOT)
+    return result.returncode == 0
+
+
+def unwritable_services(instance_dir: Path) -> list[str]:
+    return [service for service in WRITER_SERVICES if not is_writable(instance_dir, service)]
+
+
+def fix_media_permissions(instance_dir: Path) -> ContainerUser:
+    """Setzt den Eigentümer von MEDIA_ROOT auf den Container-User und prüft danach die Schreibrechte."""
+    user = container_user(instance_dir)
+    result = _run(instance_dir, OWNER_SERVICE, *chown_args(CONTAINER_MEDIA_ROOT, user), root=True)
+    if result.returncode != 0:
+        raise PermissionFixError(
+            f"Eigentümer von MEDIA_ROOT konnte nicht auf {user} gesetzt werden: "
+            f"{(result.stderr or result.stdout).strip()}"
+        )
+    failing = unwritable_services(instance_dir)
+    if failing:
+        raise PermissionFixError(
+            f"MEDIA_ROOT ist nach der Korrektur für {', '.join(failing)} nicht beschreibbar "
+            f"(Eigentümer jetzt {user})."
+        )
+    return user
+
+
+def manual_fix_hint(media_root: str, user: ContainerUser | None) -> str:
+    owner = f"{user.uid}:{user.gid}" if user else "<UID>:<GID>"
+    return f"sudo chown -R {owner} {media_root}"

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/src/katalon_cli/core/state.py

@@ -24,7 +24,7 @@ class InstallationState(BaseModel):
     version: str
     compose_revision: int
     base_url: str
-    tls_mode: str  # "standalone" | "behind-proxy" | "none"
+    tls_mode: str  # "caddy" | "standalone" | "behind-proxy" | "none"
     installed_at: datetime
     history: list[HistoryEntry] = Field(default_factory=list)
 

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/src/katalon_cli/main.py

@@ -28,9 +28,9 @@ from rich.prompt import Confirm, Prompt
 from rich.table import Table
 
 from .core import backup as backup_mod
-from .core import checks, docker, release, selfupdate
+from .core import checks, docker, permissions, release, selfupdate
 from .core import reindex as reindex_mod
-from .core.compose_gen import write_compose
+from .core.compose_gen import caddy_host, write_compose
 from .core.paths import default_instance_dir, save_instance_dir
 from .core.state import InstallationState, instance_dir_or_raise
 
@@ -57,8 +57,9 @@ def _main(
     pass
 
 TLS_CHOICES = {
-    "standalone": "Standalone — eigenes nginx mit selbstsigniertem Zertifikat (Ports 80+443)",
-    "behind-proxy": "Hinter eigenem Reverse-Proxy — kein TLS hier",
+    "caddy": "Caddy – automatische HTTPS-Zertifikate und Erneuerung (Ports 80+443)",
+    "standalone": "Selbstsigniert – eigenes nginx, Browserwarnung, keine automatische Erneuerung (Ports 80+443)",
+    "behind-proxy": "Hinter eigenem Reverse-Proxy – Zertifikate dort verwalten",
     "none": "Kein TLS (lokal / IP)",
 }
 
@@ -247,6 +248,10 @@ def _run_checks(dir: Path, ports: list[int] | None = None, need_openssl: bool =
 def _resolve_ports_and_base_url(
     base_url: str, tls_mode: str, is_localhost: bool
 ) -> tuple[str, list[int]]:
+    if tls_mode == "caddy":
+        base_url = urlparse(base_url)._replace(scheme="https").geturl()
+        caddy_host(base_url)
+        return base_url, [80, 443]
     if tls_mode == "standalone":
         return base_url, [80, 443]
 
@@ -308,16 +313,37 @@ def install(
         "sonst echte Domain (dann folgt TLS-Auswahl)."
     )
     base_url = Prompt.ask("KATALON_BASE_URL", default="http://localhost")
+    if "://" not in base_url:
+        base_url = f"http://{base_url}"
 
     console.print()
     console.print("MEDIA_ROOT — Verzeichnis auf dem Host, in dem Katalon Mediendateien ablegt.")
     media_root = Prompt.ask("MEDIA_ROOT", default=str(dir / "media"))
 
     is_localhost = urlparse(base_url).hostname in (None, "localhost", "127.0.0.1")
+    try:
+        caddy_host(f"https://{urlparse(base_url).hostname or ''}")
+        is_domain = True
+    except ValueError:
+        is_domain = False
     console.print()
-    for key, label in TLS_CHOICES.items():
-        console.print(f"  [cyan]{key}[/] — {label}")
-    tls_mode = Prompt.ask("TLS-Modus", choices=list(TLS_CHOICES), default="none" if is_localhost else "standalone")
+    if is_domain:
+        console.print(
+            "Für öffentliches HTTPS: Der A-Record muss auf die öffentliche IPv4-Adresse dieses Servers zeigen. "
+            "Ein vorhandener AAAA-Record muss auf seine erreichbare IPv6-Adresse zeigen. "
+            "DNS-Änderungen müssen bereits wirksam sein."
+        )
+        console.print(
+            "Für Caddy müssen TCP-Ports 80 und 443 öffentlich erreichbar sein "
+            "(Server-/Provider-Firewall, ggf. Portweiterleitung). "
+            "Caddy beantragt und erneuert Zertifikate automatisch, solange es läuft und erreichbar bleibt. "
+            "Die CLI prüft freie Ports lokal; öffentliche DNS-Auflösung und Erreichbarkeit musst du sicherstellen."
+        )
+    choices = [key for key in TLS_CHOICES if key != "caddy" or is_domain]
+    for key in choices:
+        console.print(f"  [cyan]{key}[/] – {TLS_CHOICES[key]}")
+    default_tls = "none" if is_localhost else ("caddy" if is_domain else "standalone")
+    tls_mode = Prompt.ask("TLS-Modus", choices=choices, default=default_tls)
 
     console.print()
     base_url, ports = _resolve_ports_and_base_url(base_url, tls_mode, is_localhost)
@@ -403,6 +429,7 @@ def _print_next_steps(dir: Path, base_url: str, show_credentials: bool = False)
     console.print()
     console.print(f"Portal:      [bold]{base_url}/[/]")
     console.print(f"Admin:       [bold]{base_url}/admin/[/]")
+    console.print(f"API:         [bold]{base_url}/v1/[/] (OpenAPI-Doku: {base_url}/api/docs)")
     creds = _first_run_credentials(dir) if show_credentials else None
     if not show_credentials:
         console.print("Admin-Passwort vergessen? [bold]katalon manage reset-admin[/]")
@@ -423,10 +450,40 @@ def _print_next_steps(dir: Path, base_url: str, show_credentials: bool = False)
     console.print("Docs:        [bold]https://katalon-collections.github.io/katalon-docs/[/]")
 
 
+def _media_root(dir: Path) -> str:
+    value = _env_value(dir, "MEDIA_ROOT") or "./media"
+    path = Path(value)
+    return str(path if path.is_absolute() else dir / path)
+
+
+def _ensure_media_permissions(dir: Path) -> bool:
+    """Macht MEDIA_ROOT für den Container-User von API/Worker beschreibbar (idempotent).
+
+    Fehler brechen nicht ab: Der Stack startet trotzdem, nur Uploads schlagen fehl."""
+    try:
+        user = permissions.fix_media_permissions(dir)
+    except permissions.PermissionFixError as exc:
+        console.print(f"[red]✖ MEDIA_ROOT {_media_root(dir)}: {exc}[/]")
+        console.print(
+            "  Uploads schlagen sonst mit HTTP 500 fehl. Manuell beheben: "
+            f"[bold]{permissions.manual_fix_hint(_media_root(dir), None)}[/] "
+            "(UID/GID: `katalon doctor`)"
+        )
+        return False
+    console.print(f"[green]✔[/] MEDIA_ROOT beschreibbar für Container-User {user}.")
+    return True
+
+
 def _start(dir: Path, show_credentials: bool = False) -> None:
+    _ensure_media_permissions(dir)
     docker.compose(dir, "up", "-d")
     console.print("[green]✔[/] Stack gestartet.")
     state = InstallationState.load(dir)
+    if state.tls_mode == "caddy":
+        console.print(
+            "Caddy beantragt beim ersten Start das HTTPS-Zertifikat; das kann kurz dauern. "
+            "Bei HTTPS-Problemen: [bold]katalon logs caddy[/]."
+        )
     _print_next_steps(dir, state.base_url, show_credentials=show_credentials)
 
 
@@ -537,8 +594,28 @@ def doctor(dir: Path | None = typer.Option(None, "--dir")):
             "[yellow]⚠ Hinweis: Port 443 ist belegt. Falls Browser http://localhost/admin/ "
             "auf https:// umleiten, Base-URL auf z. B. http://localhost:8080 anpassen.[/]"
         )
+    _check_media_writable(dir)
     docker.compose(dir, "ps")
 
+
+def _check_media_writable(dir: Path) -> bool:
+    media_root = _media_root(dir)
+    try:
+        user = permissions.container_user(dir)
+        failing = permissions.unwritable_services(dir)
+    except (permissions.PermissionFixError, docker.DockerError) as exc:
+        console.print(f"[yellow]⚠[/] MEDIA_ROOT: Prüfung nicht möglich — {exc}")
+        return False
+    if failing:
+        console.print(
+            f"[red]✖[/] MEDIA_ROOT: {media_root} ist für {', '.join(failing)} "
+            f"(Container-User {user}) nicht beschreibbar — Medien-Uploads scheitern mit HTTP 500. "
+            f"Beheben: [bold]katalon start[/] oder [bold]{permissions.manual_fix_hint(media_root, user)}[/]"
+        )
+        return False
+    console.print(f"[green]✔[/] MEDIA_ROOT: {media_root} beschreibbar für Container-User {user}")
+    return True
+
 @app.command()
 def check_updates(dir: Path | None = typer.Option(None, "--dir")):
     """Prüft, ob eine neue Katalon-Version verfügbar ist."""
@@ -620,6 +697,7 @@ def update(
             lambda: write_compose(dir, version=meta.version, base_url=state.base_url, tls_mode=state.tls_mode),
         ),
         ("Images pullen", lambda: docker.compose(dir, "pull")),
+        ("Medienrechte prüfen", lambda: _ensure_media_permissions(dir)),
         # DB-Migration läuft automatisch im api-Container-Entrypoint beim Start.
         ("Container neu starten", lambda: docker.compose(dir, "up", "-d")),
     ]
@@ -703,6 +781,7 @@ def rollback(
         write_compose(dir, version=previous.version, base_url=state.base_url, tls_mode=state.tls_mode)
         docker.compose(dir, "pull")
 
+    _ensure_media_permissions(dir)
     docker.compose(dir, "up", "-d")
     console.print("[green]✔[/] Rollback abgeschlossen.")
 

katalon_cli-0.2.1/src/katalon_cli/templates/Caddyfile.j2

@@ -0,0 +1,3 @@
+{{ host }} {
+    reverse_proxy nginx:80
+}

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/src/katalon_cli/templates/compose.yaml.j2

@@ -159,6 +159,7 @@ services:
 {% if tls_mode == "standalone" %}
       - ./certs:/etc/nginx/certs:ro
 {% endif %}
+{% if tls_mode != "caddy" %}
     ports:
 {% if tls_mode == "standalone" %}
       - "80:80"
@@ -167,12 +168,32 @@ services:
       - "127.0.0.1:{{ port or 8080 }}:80"
 {% else %}
       - "{{ port or 80 }}:80"
+{% endif %}
 {% endif %}
     depends_on:
       api: { condition: service_healthy }
       admin: { condition: service_healthy }
       portal: { condition: service_healthy }
 
+{% if tls_mode == "caddy" %}
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      nginx: { condition: service_started }
+
+{% endif %}
 volumes:
   db_data:
   es_data:
+{% if tls_mode == "caddy" %}
+  caddy_data:
+  caddy_config:
+{% endif %}

{katalon_cli-0.1.20 → katalon_cli-0.2.1}/src/katalon_cli/templates/nginx.conf.j2

@@ -23,7 +23,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto {{ '$http_x_forwarded_proto' if tls_mode == 'caddy' else '$scheme' }};
     }
 
     location /v1/ {
@@ -32,7 +32,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto {{ '$http_x_forwarded_proto' if tls_mode == 'caddy' else '$scheme' }};
     }
 
     location /portal/v1/ {
@@ -41,7 +41,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto {{ '$http_x_forwarded_proto' if tls_mode == 'caddy' else '$scheme' }};
     }
 
     location = /health {
@@ -50,7 +50,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto {{ '$http_x_forwarded_proto' if tls_mode == 'caddy' else '$scheme' }};
     }
 
     location = /oai {
@@ -59,7 +59,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto {{ '$http_x_forwarded_proto' if tls_mode == 'caddy' else '$scheme' }};
     }
 
     location ^~ /ark:/ {
@@ -68,7 +68,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto {{ '$http_x_forwarded_proto' if tls_mode == 'caddy' else '$scheme' }};
     }
 
     location /iiif/ {