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

katalon_cli-0.2.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.3
+Name: katalon-cli
+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>
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.9
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.9
+Requires-Dist: jinja2>=3.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# katalon-cli
+
+Installer & Updater für [Katalon Collections](https://github.com/katalon-collections/katalon) Production-Instanzen.
+Verwaltet eine Instanz unter einem frei gewählten Zielverzeichnis — pullt gepinnte
+Release-Images, generiert `compose.yaml`, macht Backups vor jedem Update, kann rollbacken.
+
+## Installation
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install katalon-cli
+```
+
+## Nutzung
+
+```bash
+katalon install              # interaktiver Setup-Wizard (Rich-Prompts + Progress)
+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, 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)
+katalon restore DUMP           # DB durch pg_dump ersetzen (-Fc oder SQL), danach Reindex
+katalon reindex                # Suchindex neu aufbauen, mit Fortschrittsanzeige
+```
+
+Ein DB-Dump enthält nicht den Suchindex (Elasticsearch). `restore` baut ihn deshalb nach dem
+Einspielen neu auf (`--no-reindex` zum Überspringen, später `katalon reindex`). Bei großen
+Beständen dauert das lange (ca. 45 Min. für 80k Datensätze). Außerdem prüft `katalon` einmal
+täglich auf neue Versionen (abschalten: `KATALON_NO_UPDATE_CHECK=1`).
+
+`install` ohne `--dir` fragt das Zielverzeichnis interaktiv ab. Nach erfolgreicher Einrichtung
+wird der absolute Pfad benutzerweit in `~/.config/katalon/instance` gespeichert.
+Bei gesetztem, absolutem `XDG_CONFIG_HOME` liegt die Datei stattdessen unter
+`$XDG_CONFIG_HOME/katalon/instance`. Das Konfigurationsverzeichnis wird bei Bedarf angelegt.
+Alle weiteren Befehle verwenden den gespeicherten Pfad, unabhängig vom Arbeitsverzeichnis.
+Ohne gespeicherten Pfad ist der Default auf allen Plattformen `~/katalon`.
+
+Alle Befehle unterstützen `--dir PATH`: überschreibt den Pfad nur für diesen Aufruf.
+Eine erfolgreiche neue Installation speichert ihr Zielverzeichnis als neuen Default.
+Bestehende Instanzen lassen sich weiterhin mit `--dir` verwenden; alternativ ihren absoluten
+Pfad als einzige Zeile in die Konfigurationsdatei eintragen.
+`install`/`update` fragen interaktiv (Auswahl über `rich.prompt`),
+`update`/`rollback` haben `--yes` zum Überspringen der Rückfrage.
+
+```bash
+katalon install --dir ~/meine-katalon-instanz
+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
+uv sync
+uv run katalon --help
+uv run pytest
+```
+
+## Architektur
+
+- `core/state.py` — `installation.json`, Single Source of Truth für laufende Version.
+- `core/release.py` — GitHub-Release-Metadaten (`katalon-release.json` Asset). Enthält
+  optional `env_vars`/`deprecated_env_vars`: `install`/`update` ergänzen neue Pflichtvariablen
+  automatisch (Secret generieren oder Default übernehmen), fragen bei fehlendem Default interaktiv
+  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` 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
+  und bei Updates nicht angefasst). Optionale Env-Vars (Admin-Login, SMTP, Geonames, …) landet
+  auskommentiert in `.env`.
+- `core/backup.py` — `pg_dump` vor jedem Update; Rollback restauriert Dump statt `alembic downgrade`.
+- `core/docker.py` — dünner `docker compose`-Subprocess-Wrapper.
+- `main.py` — Typer-Commands, interaktive Teile über `rich.prompt`/`rich.progress`.

katalon_cli-0.2.1/README.md

@@ -0,0 +1,132 @@
+# katalon-cli
+
+Installer & Updater für [Katalon Collections](https://github.com/katalon-collections/katalon) Production-Instanzen.
+Verwaltet eine Instanz unter einem frei gewählten Zielverzeichnis — pullt gepinnte
+Release-Images, generiert `compose.yaml`, macht Backups vor jedem Update, kann rollbacken.
+
+## Installation
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install katalon-cli
+```
+
+## Nutzung
+
+```bash
+katalon install              # interaktiver Setup-Wizard (Rich-Prompts + Progress)
+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, 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)
+katalon restore DUMP           # DB durch pg_dump ersetzen (-Fc oder SQL), danach Reindex
+katalon reindex                # Suchindex neu aufbauen, mit Fortschrittsanzeige
+```
+
+Ein DB-Dump enthält nicht den Suchindex (Elasticsearch). `restore` baut ihn deshalb nach dem
+Einspielen neu auf (`--no-reindex` zum Überspringen, später `katalon reindex`). Bei großen
+Beständen dauert das lange (ca. 45 Min. für 80k Datensätze). Außerdem prüft `katalon` einmal
+täglich auf neue Versionen (abschalten: `KATALON_NO_UPDATE_CHECK=1`).
+
+`install` ohne `--dir` fragt das Zielverzeichnis interaktiv ab. Nach erfolgreicher Einrichtung
+wird der absolute Pfad benutzerweit in `~/.config/katalon/instance` gespeichert.
+Bei gesetztem, absolutem `XDG_CONFIG_HOME` liegt die Datei stattdessen unter
+`$XDG_CONFIG_HOME/katalon/instance`. Das Konfigurationsverzeichnis wird bei Bedarf angelegt.
+Alle weiteren Befehle verwenden den gespeicherten Pfad, unabhängig vom Arbeitsverzeichnis.
+Ohne gespeicherten Pfad ist der Default auf allen Plattformen `~/katalon`.
+
+Alle Befehle unterstützen `--dir PATH`: überschreibt den Pfad nur für diesen Aufruf.
+Eine erfolgreiche neue Installation speichert ihr Zielverzeichnis als neuen Default.
+Bestehende Instanzen lassen sich weiterhin mit `--dir` verwenden; alternativ ihren absoluten
+Pfad als einzige Zeile in die Konfigurationsdatei eintragen.
+`install`/`update` fragen interaktiv (Auswahl über `rich.prompt`),
+`update`/`rollback` haben `--yes` zum Überspringen der Rückfrage.
+
+```bash
+katalon install --dir ~/meine-katalon-instanz
+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
+uv sync
+uv run katalon --help
+uv run pytest
+```
+
+## Architektur
+
+- `core/state.py` — `installation.json`, Single Source of Truth für laufende Version.
+- `core/release.py` — GitHub-Release-Metadaten (`katalon-release.json` Asset). Enthält
+  optional `env_vars`/`deprecated_env_vars`: `install`/`update` ergänzen neue Pflichtvariablen
+  automatisch (Secret generieren oder Default übernehmen), fragen bei fehlendem Default interaktiv
+  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` 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
+  und bei Updates nicht angefasst). Optionale Env-Vars (Admin-Login, SMTP, Geonames, …) landet
+  auskommentiert in `.env`.
+- `core/backup.py` — `pg_dump` vor jedem Update; Rollback restauriert Dump statt `alembic downgrade`.
+- `core/docker.py` — dünner `docker compose`-Subprocess-Wrapper.
+- `main.py` — Typer-Commands, interaktive Teile über `rich.prompt`/`rich.progress`.

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

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

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

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

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

@@ -0,0 +1,132 @@
+"""Backup vor jedem Update, Restore für Rollback. Kein Alembic-Downgrade — s. Plan."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+from . import docker
+
+
+class BackupError(RuntimeError):
+    pass
+
+
+def create_backup(instance_dir: Path) -> Path:
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H%M")
+    backup_dir = instance_dir / "backups" / timestamp
+    backup_dir.mkdir(parents=True, exist_ok=True)
+
+    dump = docker.compose(
+        instance_dir,
+        "exec",
+        "-T",
+        "db",
+        "pg_dump",
+        "-U",
+        "katalon",
+        "katalon",
+        check=True,
+        capture=True,
+    )
+    (backup_dir / "pg_dump.sql").write_text(dump.stdout)
+
+    for name in (".env", "installation.json"):
+        src = instance_dir / name
+        if src.exists():
+            shutil.copy2(src, backup_dir / name)
+
+    return backup_dir
+
+
+def restore_backup(instance_dir: Path, backup_dir: Path) -> None:
+    dump_file = backup_dir / "pg_dump.sql"
+    if not dump_file.exists():
+        raise BackupError(f"Kein pg_dump.sql in {backup_dir}")
+
+    docker.compose(instance_dir, "exec", "-T", "db", "dropdb", "-U", "katalon", "katalon")
+    docker.compose(instance_dir, "exec", "-T", "db", "createdb", "-U", "katalon", "katalon")
+    subprocess.run(
+        [*docker.compose_command(), *docker.compose_files(instance_dir),
+         "exec", "-T", "db", "psql", "-U", "katalon", "katalon"],
+        input=dump_file.read_text(),
+        cwd=instance_dir,
+        text=True,
+        check=True,
+    )
+
+    for name in (".env", "installation.json"):
+        src = backup_dir / name
+        if src.exists():
+            shutil.copy2(src, instance_dir / name)
+
+
+def latest_backup(instance_dir: Path) -> Path | None:
+    backups_dir = instance_dir / "backups"
+    if not backups_dir.exists():
+        return None
+    candidates = sorted(backups_dir.iterdir(), reverse=True)
+    return candidates[0] if candidates else None
+
+
+def dump_format(dump: Path) -> str:
+    """'custom' für pg_dump -Fc (Magic `PGDMP`), sonst 'sql' (Plain-Text)."""
+    with dump.open("rb") as fh:
+        return "custom" if fh.read(5) == b"PGDMP" else "sql"
+
+
+def restore_dump(
+    instance_dir: Path,
+    dump: Path,
+    on_progress: Callable[[int], None] | None = None,
+    chunk_size: int = 1024 * 1024,
+) -> str:
+    """Ersetzt die DB `katalon` durch den Dump. Gibt das erkannte Format zurück.
+
+    Die Datei wird in Blöcken an pg_restore/psql gestreamt; `on_progress` bekommt
+    die bisher gesendeten Bytes.
+    """
+    if not dump.is_file():
+        raise BackupError(f"Dump nicht gefunden: {dump}")
+    fmt = dump_format(dump)
+
+    docker.compose(
+        instance_dir, "exec", "-T", "db", "dropdb", "-U", "katalon", "--if-exists", "--force", "katalon"
+    )
+    docker.compose(instance_dir, "exec", "-T", "db", "createdb", "-U", "katalon", "katalon")
+
+    if fmt == "custom":
+        tool = ["pg_restore", "-U", "katalon", "-d", "katalon", "--no-owner", "--exit-on-error"]
+    else:
+        tool = ["psql", "-U", "katalon", "-d", "katalon", "-q", "-v", "ON_ERROR_STOP=1"]
+
+    sent = 0
+    with tempfile.TemporaryFile() as err, dump.open("rb") as src:
+        proc = subprocess.Popen(
+            [*docker.compose_command(), *docker.compose_files(instance_dir), "exec", "-T", "db", *tool],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+            stderr=err,
+            cwd=instance_dir,
+        )
+        assert proc.stdin is not None
+        try:
+            while chunk := src.read(chunk_size):
+                proc.stdin.write(chunk)
+                sent += len(chunk)
+                if on_progress:
+                    on_progress(sent)
+            proc.stdin.close()
+        except BrokenPipeError:
+            pass  # Tool ist vorzeitig beendet — Fehlertext steht unten in stderr
+        returncode = proc.wait()
+        err.seek(0)
+        message = err.read().decode(errors="replace").strip()
+
+    if returncode != 0:
+        raise BackupError(f"Restore fehlgeschlagen ({tool[0]}, Exit {returncode}):\n{message[-2000:]}")
+    return fmt

{katalon_cli-0.1.19 → 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}"