katalon-cli 0.1.0__tar.gz

katalon_cli-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: katalon-cli
+Version: 0.1.0
+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](https://github.com/karkraeg/Katalon) Production-Instanzen.
+Verwaltet eine Instanz unter einem Zielverzeichnis (z.B. `/opt/katalon/`) — 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 update                # interaktives Update, Backup zuerst immer
+katalon rollback               # letztes Backup einspielen
+katalon doctor                 # Docker, Diskspace, Ports prüfen
+katalon backup                 # manuelles Backup
+katalon logs [service]
+```
+
+Alle Befehle: `--dir PATH` (default `/opt/katalon`). `install`/`update` fragen interaktiv
+(Auswahl über `rich.prompt`), `update`/`rollback` haben `--yes` zum Überspringen der Rückfrage.
+
+## 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), 1h Cache.
+- `core/compose_gen.py` + `templates/compose.yaml.j2` — rendert `compose.yaml` aus Version + TLS-Modus.
+- `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.0/README.md

@@ -0,0 +1,44 @@
+# katalon-cli
+
+Installer & Updater für [Katalon](https://github.com/karkraeg/Katalon) Production-Instanzen.
+Verwaltet eine Instanz unter einem Zielverzeichnis (z.B. `/opt/katalon/`) — 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 update                # interaktives Update, Backup zuerst immer
+katalon rollback               # letztes Backup einspielen
+katalon doctor                 # Docker, Diskspace, Ports prüfen
+katalon backup                 # manuelles Backup
+katalon logs [service]
+```
+
+Alle Befehle: `--dir PATH` (default `/opt/katalon`). `install`/`update` fragen interaktiv
+(Auswahl über `rich.prompt`), `update`/`rollback` haben `--yes` zum Überspringen der Rückfrage.
+
+## 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), 1h Cache.
+- `core/compose_gen.py` + `templates/compose.yaml.j2` — rendert `compose.yaml` aus Version + TLS-Modus.
+- `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.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "katalon-cli"
+version = "0.1.0"
+description = "Installer & Updater CLI für Katalon Production-Instanzen"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.15",
+    "rich>=13.9",
+    "httpx>=0.28",
+    "pydantic>=2.9",
+    "jinja2>=3.1",
+]
+
+[[project.authors]]
+name = "Karl Krägelin"
+email = "karlkraegelin@gmail.com"
+
+[project.scripts]
+katalon = "katalon_cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8.3"]

katalon_cli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "katalon-cli"
+version = "0.1.0"
+description = "Installer & Updater CLI für Katalon Production-Instanzen"
+readme = "README.md"
+authors = [
+    { name = "Karl Krägelin", email = "karlkraegelin@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.15",
+    "rich>=13.9",
+    "httpx>=0.28",
+    "pydantic>=2.9",
+    "jinja2>=3.1",
+]
+
+[project.scripts]
+katalon = "katalon_cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+]

katalon_cli-0.1.0/src/katalon_cli/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from katalon-cli!"

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

@@ -0,0 +1,71 @@
+"""Backup vor jedem Update, Restore für Rollback. Kein Alembic-Downgrade — s. Plan."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+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(), "-f", str(instance_dir / "compose.yaml"),
+         "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

katalon_cli-0.1.0/src/katalon_cli/core/checks.py

@@ -0,0 +1,61 @@
+"""Preflight-Checks für `katalon install` und `katalon doctor`."""
+
+from __future__ import annotations
+
+import shutil
+import socket
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+MIN_FREE_DISK_GB = 5
+
+
+@dataclass
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str
+
+
+def check_docker() -> CheckResult:
+    if not shutil.which("docker"):
+        return CheckResult("Docker", False, "nicht gefunden — https://docs.docker.com/get-docker/")
+    version = subprocess.run(["docker", "--version"], capture_output=True, text=True)
+    return CheckResult("Docker", True, version.stdout.strip())
+
+
+def check_compose() -> CheckResult:
+    probe = subprocess.run(["docker", "compose", "version"], capture_output=True, text=True)
+    if probe.returncode == 0:
+        return CheckResult("Docker Compose", True, probe.stdout.strip())
+    if shutil.which("docker-compose"):
+        return CheckResult("Docker Compose", True, "docker-compose (standalone)")
+    return CheckResult("Docker Compose", False, "nicht gefunden")
+
+
+def check_disk_space(path: Path, min_gb: int = MIN_FREE_DISK_GB) -> CheckResult:
+    path.mkdir(parents=True, exist_ok=True)
+    free_gb = shutil.disk_usage(path).free / (1024**3)
+    ok = free_gb >= min_gb
+    return CheckResult(
+        "Diskspace", ok, f"{free_gb:.1f} GB frei (min. {min_gb} GB) in {path}"
+    )
+
+def check_ports(ports: list[int]) -> CheckResult:
+    busy = []
+    for port in ports:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(0.5)
+            if s.connect_ex(("127.0.0.1", port)) == 0:
+                busy.append(port)
+    if busy:
+        return CheckResult("Ports", False, f"belegt: {', '.join(map(str, busy))}")
+    return CheckResult("Ports", True, f"frei: {', '.join(map(str, ports))}")
+
+
+def run_all(instance_dir: Path, ports: list[int] | None = None) -> list[CheckResult]:
+    results = [check_docker(), check_compose(), check_disk_space(instance_dir)]
+    if ports:
+        results.append(check_ports(ports))
+    return results

katalon_cli-0.1.0/src/katalon_cli/core/compose_gen.py

@@ -0,0 +1,37 @@
+"""Rendert compose.yaml aus Template + Release-Version + TLS-Modus."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+_env = Environment(
+    loader=PackageLoader("katalon_cli", "templates"),
+    autoescape=select_autoescape(disabled_extensions=(".yaml", ".j2")),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+def render_compose(
+    *,
+    version: str,
+    base_url: str,
+    tls_mode: str,
+    registry: str = "ghcr.io/karkraeg/katalon",
+) -> str:
+    template = _env.get_template("compose.yaml.j2")
+    return template.render(
+        version=version,
+        base_url=base_url,
+        tls_mode=tls_mode,
+        registry=registry,
+    )
+
+
+def write_compose(instance_dir: Path, **kwargs) -> Path:
+    content = render_compose(**kwargs)
+    path = instance_dir / "compose.yaml"
+    path.write_text(content)
+    return path

katalon_cli-0.1.0/src/katalon_cli/core/docker.py

@@ -0,0 +1,44 @@
+"""Dünner Wrapper um `docker compose` — kein docker-py nötig, CLI reicht."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class DockerError(RuntimeError):
+    pass
+
+
+def compose_command() -> list[str]:
+    if shutil.which("docker") is None:
+        raise DockerError("Docker ist nicht installiert oder nicht im PATH.")
+    probe = subprocess.run(
+        ["docker", "compose", "version"], capture_output=True, text=True
+    )
+    if probe.returncode == 0:
+        return ["docker", "compose"]
+    if shutil.which("docker-compose"):
+        return ["docker-compose"]
+    raise DockerError("Docker Compose ist nicht installiert.")
+
+
+def compose(
+    instance_dir: Path, *args: str, check: bool = True, capture: bool = False
+) -> subprocess.CompletedProcess:
+    cmd = [*compose_command(), "-f", str(instance_dir / "compose.yaml"), *args]
+    return subprocess.run(
+        cmd,
+        cwd=instance_dir,
+        check=check,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def is_healthy(instance_dir: Path, service: str = "api") -> bool:
+    result = compose(
+        instance_dir, "ps", "--format", "json", service, check=False, capture=True
+    )
+    return result.returncode == 0 and '"Health":"healthy"' in (result.stdout or "")

katalon_cli-0.1.0/src/katalon_cli/core/paths.py

@@ -0,0 +1,17 @@
+"""Plattformabhängiger Default-Pfad für Instanzverzeichnisse.
+
+/opt ist Linux-Server-Konvention für selbstverwaltete Dienste und dort meist
+nur mit sudo beschreibbar. macOS (lokales Testen/Entwickeln) hat keine
+vergleichbare Konvention mit Schreibrechten ohne sudo — dort ins Home.
+"""
+
+from __future__ import annotations
+
+import platform
+from pathlib import Path
+
+
+def default_instance_dir() -> Path:
+    if platform.system() == "Darwin":
+        return Path.home() / "katalon"
+    return Path("/opt/katalon")

katalon_cli-0.1.0/src/katalon_cli/core/release.py

@@ -0,0 +1,68 @@
+"""GitHub-Release-Metadata für Katalon (nicht katalon-cli selbst)."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import httpx
+from pydantic import BaseModel
+
+GITHUB_REPO = "karkraeg/Katalon"
+CACHE_TTL_SECONDS = 3600
+CACHE_PATH = Path.home() / ".cache" / "katalon-cli" / "releases.json"
+
+
+class ReleaseRequirements(BaseModel):
+    postgres: str | None = None
+    elasticsearch: str | None = None
+
+
+class ReleaseMetadata(BaseModel):
+    version: str
+    minimum_installer_version: str
+    migration_required: bool
+    breaking: bool
+    compose_revision: int
+    requires: ReleaseRequirements = ReleaseRequirements()
+
+
+def _fetch_release_asset(tag: str | None) -> dict:
+    """Lädt katalon-release.json vom GitHub-Release (tag=None → latest)."""
+    ref = "latest" if tag is None else f"tags/{tag}"
+    with httpx.Client(timeout=15) as client:
+        release = client.get(
+            f"https://api.github.com/repos/{GITHUB_REPO}/releases/{ref}"
+        )
+        release.raise_for_status()
+        data = release.json()
+
+    asset = next(
+        (a for a in data["assets"] if a["name"] == "katalon-release.json"), None
+    )
+    if asset is None:
+        raise ValueError(
+            f"Release {data.get('tag_name', tag)} hat kein katalon-release.json Asset."
+        )
+    with httpx.Client(timeout=15) as client:
+        asset_resp = client.get(asset["browser_download_url"])
+        asset_resp.raise_for_status()
+        return asset_resp.json()
+
+
+def get_latest_release(*, use_cache: bool = True) -> ReleaseMetadata:
+    if use_cache and CACHE_PATH.exists():
+        age = time.time() - CACHE_PATH.stat().st_mtime
+        if age < CACHE_TTL_SECONDS:
+            return ReleaseMetadata.model_validate_json(CACHE_PATH.read_text())
+
+    payload = _fetch_release_asset(tag=None)
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CACHE_PATH.write_text(json.dumps(payload))
+    return ReleaseMetadata.model_validate(payload)
+
+
+def get_release(version: str) -> ReleaseMetadata:
+    payload = _fetch_release_asset(tag=f"v{version.lstrip('v')}")
+    return ReleaseMetadata.model_validate(payload)

katalon_cli-0.1.0/src/katalon_cli/core/state.py

@@ -0,0 +1,67 @@
+"""installation.json — Single Source of Truth für die laufende Instanz."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+STATE_FILENAME = "installation.json"
+
+
+class HistoryEntry(BaseModel):
+    version: str
+    compose_revision: int
+    action: str  # "install" | "update" | "rollback"
+    at: datetime
+
+
+class InstallationState(BaseModel):
+    version: str
+    compose_revision: int
+    base_url: str
+    tls_mode: str  # "standalone" | "behind-proxy" | "none"
+    installed_at: datetime
+    history: list[HistoryEntry] = Field(default_factory=list)
+
+    @classmethod
+    def load(cls, instance_dir: Path) -> "InstallationState":
+        path = instance_dir / STATE_FILENAME
+        if not path.exists():
+            raise FileNotFoundError(
+                f"{path} nicht gefunden — ist dies ein Katalon-Instanzverzeichnis?"
+            )
+        return cls.model_validate_json(path.read_text())
+
+    def save(self, instance_dir: Path) -> None:
+        path = instance_dir / STATE_FILENAME
+        path.write_text(self.model_dump_json(indent=2))
+
+    def record(self, version: str, compose_revision: int, action: str) -> None:
+        self.history.append(
+            HistoryEntry(
+                version=version,
+                compose_revision=compose_revision,
+                action=action,
+                at=datetime.now(timezone.utc),
+            )
+        )
+        self.version = version
+        self.compose_revision = compose_revision
+
+    def previous(self) -> HistoryEntry | None:
+        """Letzter History-Eintrag vor dem aktuellen Stand, für Rollback."""
+        if len(self.history) < 2:
+            return None
+        return self.history[-2]
+
+
+def instance_dir_or_raise(path: Path) -> Path:
+    if not (path / STATE_FILENAME).exists():
+        raise FileNotFoundError(
+            f"Kein Katalon in {path} gefunden (installation.json fehlt). "
+            "Erst `katalon install` ausführen."
+        )
+    return path

katalon_cli-0.1.0/src/katalon_cli/main.py

@@ -0,0 +1,300 @@
+"""katalon — Installer & Updater CLI für Production-Instanzen."""
+
+from __future__ import annotations
+
+import platform
+import secrets
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+
+from .core import backup as backup_mod
+from .core import checks, docker, release
+from .core.compose_gen import write_compose
+from .core.paths import default_instance_dir
+from .core.state import InstallationState, instance_dir_or_raise
+
+app = typer.Typer(add_completion=False, help="Installer & Updater für Katalon.")
+console = Console()
+
+DEFAULT_DIR = default_instance_dir()
+
+TLS_CHOICES = {
+    "standalone": "Standalone — Katalon verwaltet HTTPS via Caddy (Ports 80+443)",
+    "behind-proxy": "Hinter eigenem Reverse-Proxy — kein TLS hier",
+    "none": "Kein TLS (lokal / IP)",
+}
+
+
+def _run_checks(dir: Path, ports: list[int] | None = None) -> bool:
+    ok = True
+    for result in checks.run_all(dir, ports=ports):
+        icon, style = ("✔", "green") if result.ok else ("✖", "red")
+        console.print(f"[{style}]{icon}[/] {result.name}: {result.detail}")
+        ok = ok and result.ok
+    return ok
+
+
+@app.command()
+def install(
+    dir: Path = typer.Option(
+        None, "--dir", help=f"Zielverzeichnis der Instanz (Default für dieses OS: {DEFAULT_DIR})"
+    ),
+):
+    """Interaktiver Setup-Wizard für eine neue Instanz."""
+    console.rule("[bold]Katalon Setup[/]")
+
+    if dir is None:
+        console.print(f"Zielverzeichnis — Standard für {platform.system()}: [cyan]{DEFAULT_DIR}[/]")
+        dir = Path(Prompt.ask("Zielverzeichnis", default=str(DEFAULT_DIR)))
+
+    if (dir / "installation.json").exists():
+        console.print(f"[red]✖[/] {dir} ist bereits eine Katalon-Instanz.")
+        raise typer.Exit(1)
+
+    console.print()
+    console.print(
+        "KATALON_BASE_URL — [cyan]http://localhost[/] zum lokalen Testen (kein TLS), "
+        "sonst echte Domain (dann folgt TLS-Auswahl)."
+    )
+    base_url = Prompt.ask("KATALON_BASE_URL", default="http://localhost")
+
+    tls_mode = "none"
+    if urlparse(base_url).hostname not in (None, "localhost", "127.0.0.1"):
+        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="standalone")
+
+    console.print()
+    console.rule("Preflight-Checks")
+    ports = [80, 443] if tls_mode == "standalone" else None
+    if not _run_checks(dir, ports=ports):
+        console.print("[red]Abgebrochen — Check fehlgeschlagen.[/]")
+        raise typer.Exit(1)
+
+    console.print()
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), console=console) as progress:
+        task = progress.add_task("Lade Release-Metadaten …", total=None)
+        try:
+            meta = release.get_latest_release()
+        except Exception as exc:  # noqa: BLE001
+            progress.stop()
+            console.print(f"[red]✖ Release-Metadaten konnten nicht geladen werden: {exc}[/]")
+            raise typer.Exit(1) from exc
+        progress.update(task, description=f"Release {meta.version} gefunden")
+
+        progress.add_task("Schreibe compose.yaml + .env …", total=None)
+        dir.mkdir(parents=True, exist_ok=True)
+        write_compose(dir, version=meta.version, base_url=base_url, tls_mode=tls_mode)
+
+        env_path = dir / ".env"
+        if not env_path.exists():
+            env_path.write_text(
+                f"KATALON_BASE_URL={base_url}\n"
+                f"POSTGRES_PASSWORD={secrets.token_urlsafe(24)}\n"
+                f"SECRET_KEY={secrets.token_urlsafe(32)}\n"
+            )
+
+        state = InstallationState(
+            version=meta.version,
+            compose_revision=meta.compose_revision,
+            base_url=base_url,
+            tls_mode=tls_mode,
+            installed_at=datetime.now(timezone.utc),
+        )
+        state.record(meta.version, meta.compose_revision, "install")
+        state.save(dir)
+
+    console.print(f"[green]✔[/] Instanz eingerichtet in [bold]{dir}[/]")
+    console.print("Starten mit: [bold]katalon start --dir " + str(dir) + "[/]")
+
+
+@app.command()
+def start(dir: Path = typer.Option(DEFAULT_DIR, "--dir")):
+    """Stack starten."""
+    instance_dir_or_raise(dir)
+    docker.compose(dir, "up", "-d")
+    console.print("[green]✔[/] Stack gestartet.")
+
+
+@app.command()
+def stop(dir: Path = typer.Option(DEFAULT_DIR, "--dir")):
+    """Stack stoppen."""
+    instance_dir_or_raise(dir)
+    docker.compose(dir, "stop")
+    console.print("[green]✔[/] Stack gestoppt.")
+
+
+@app.command()
+def restart(dir: Path = typer.Option(DEFAULT_DIR, "--dir")):
+    """Stack neu starten."""
+    instance_dir_or_raise(dir)
+    docker.compose(dir, "restart")
+    console.print("[green]✔[/] Stack neu gestartet.")
+
+
+@app.command()
+def status(dir: Path = typer.Option(DEFAULT_DIR, "--dir")):
+    """Versionen, Container-Health, Diskspace."""
+    instance_dir_or_raise(dir)
+    state = InstallationState.load(dir)
+
+    table = Table(show_header=False)
+    table.add_row("Version", state.version)
+    table.add_row("Compose-Revision", str(state.compose_revision))
+    table.add_row("Base URL", state.base_url)
+    table.add_row("TLS-Modus", state.tls_mode)
+    table.add_row("Installiert", str(state.installed_at))
+    console.print(table)
+
+    docker.compose(dir, "ps")
+
+
+@app.command()
+def logs(
+    service: str = typer.Argument(None, help="Service-Name, leer = alle"),
+    dir: Path = typer.Option(DEFAULT_DIR, "--dir"),
+    follow: bool = typer.Option(True, "--follow/--no-follow"),
+):
+    """Wrapper um docker compose logs."""
+    instance_dir_or_raise(dir)
+    args = ["logs"]
+    if follow:
+        args.append("-f")
+    if service:
+        args.append(service)
+    docker.compose(dir, *args)
+
+
+@app.command()
+def doctor(dir: Path = typer.Option(DEFAULT_DIR, "--dir")):
+    """Diagnose: Docker, Diskspace, Ports, DB-Connectivity."""
+    _run_checks(dir, ports=[80, 443])
+
+
+@app.command()
+def backup(dir: Path = typer.Option(DEFAULT_DIR, "--dir")):
+    """Manuelles Backup (Postgres-Dump + .env + installation.json)."""
+    instance_dir_or_raise(dir)
+    path = backup_mod.create_backup(dir)
+    console.print(f"[green]✔[/] Backup erstellt: {path}")
+
+
+@app.command()
+def update(
+    dir: Path = typer.Option(DEFAULT_DIR, "--dir"),
+    target: str = typer.Option(None, "--target", help="Zielversion, default = latest"),
+    yes: bool = typer.Option(False, "--yes", help="Ohne Rückfrage"),
+):
+    """Update auf neue Version — Backup zuerst, immer."""
+    instance_dir_or_raise(dir)
+    state = InstallationState.load(dir)
+    meta = release.get_release(target) if target else release.get_latest_release()
+
+    if meta.version == state.version:
+        console.print(f"[green]✔[/] Bereits auf aktueller Version {meta.version}.")
+        return
+
+    console.rule("Update")
+    console.print(f"Aktuell: [bold]{state.version}[/]  →  Ziel: [bold]{meta.version}[/]")
+    if meta.breaking:
+        console.print("[red]⚠ Breaking Change in diesem Release.[/]")
+    if meta.migration_required:
+        console.print("[yellow]⚠ DB-Migration erforderlich.[/]")
+    if meta.compose_revision != state.compose_revision:
+        console.print(
+            f"[yellow]⚠ compose.yaml wird neu generiert "
+            f"(Revision {state.compose_revision} → {meta.compose_revision})[/]"
+        )
+
+    if not yes and not Confirm.ask("Update durchführen?"):
+        raise typer.Exit(0)
+
+    steps = [
+        ("Backup erstellen", lambda: backup_mod.create_backup(dir)),
+        (
+            "compose.yaml rendern",
+            lambda: write_compose(dir, version=meta.version, base_url=state.base_url, tls_mode=state.tls_mode),
+        ),
+        ("Images pullen", lambda: docker.compose(dir, "pull")),
+        ("Container neu starten", lambda: docker.compose(dir, "up", "-d")),
+    ]
+    if meta.migration_required:
+        steps.append(
+            ("Migration ausführen", lambda: docker.compose(dir, "exec", "api", "alembic", "upgrade", "head"))
+        )
+
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), console=console) as progress:
+        for description, action in steps:
+            task = progress.add_task(description, total=None)
+            action()
+            progress.update(task, description=f"[green]✔[/] {description}")
+
+        task = progress.add_task("Warte auf Healthcheck …", total=None)
+        healthy = False
+        import time
+
+        for _ in range(30):
+            if docker.is_healthy(dir):
+                healthy = True
+                break
+            time.sleep(2)
+        progress.update(
+            task,
+            description="[green]✔ Healthcheck OK[/]" if healthy else "[red]✖ Healthcheck fehlgeschlagen[/]",
+        )
+
+    if not healthy:
+        console.print("[red]✖ Healthcheck fehlgeschlagen — `katalon rollback` erwägen.[/]")
+        raise typer.Exit(1)
+
+    state.record(meta.version, meta.compose_revision, "update")
+    state.save(dir)
+    console.print(f"[green]✔[/] Update auf {meta.version} abgeschlossen.")
+
+
+@app.command()
+def rollback(
+    dir: Path = typer.Option(DEFAULT_DIR, "--dir"),
+    yes: bool = typer.Option(False, "--yes"),
+):
+    """Letztes Backup einspielen (kein Alembic-Downgrade)."""
+    instance_dir_or_raise(dir)
+    backup_dir = backup_mod.latest_backup(dir)
+    if backup_dir is None:
+        console.print("[red]✖[/] Kein Backup vorhanden.")
+        raise typer.Exit(1)
+
+    console.print(f"[yellow]⚠[/] Rollback auf Backup {backup_dir.name} — Daten seit diesem Backup gehen verloren.")
+    if not yes and not Confirm.ask("Fortfahren?"):
+        raise typer.Exit(0)
+
+    state = InstallationState.load(dir)
+    previous = state.previous()
+
+    backup_mod.restore_backup(dir, backup_dir)
+    if previous:
+        write_compose(dir, version=previous.version, base_url=state.base_url, tls_mode=state.tls_mode)
+        docker.compose(dir, "pull")
+
+    docker.compose(dir, "up", "-d")
+    console.print("[green]✔[/] Rollback abgeschlossen.")
+
+
+def main() -> None:
+    try:
+        app()
+    except (FileNotFoundError, docker.DockerError, backup_mod.BackupError) as exc:
+        console.print(f"[red]✖[/] {exc}")
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,11 @@
+{{ base_url_host }} {
+    handle_path /api/* {
+        reverse_proxy api:8000
+    }
+    handle_path /admin/* {
+        reverse_proxy admin:80
+    }
+    handle {
+        reverse_proxy portal:80
+    }
+}

katalon_cli-0.1.0/src/katalon_cli/templates/compose.yaml.j2

@@ -0,0 +1,99 @@
+
+services:
+  db:
+    image: postgis/postgis:16-3.4
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: katalon
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: katalon
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U katalon"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.15.0
+    restart: unless-stopped
+    environment:
+      discovery.type: single-node
+      xpack.security.enabled: "false"
+      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
+    volumes:
+      - es_data:/usr/share/elasticsearch/data
+
+  cantaloupe:
+    image: {{ registry }}-cantaloupe:{{ version }}
+    restart: unless-stopped
+    volumes:
+      - ./media:/media:ro
+
+  api:
+    image: {{ registry }}-api:{{ version }}
+    restart: unless-stopped
+    env_file: .env
+    depends_on:
+      db: { condition: service_healthy }
+    volumes:
+      - ./media:/var/lib/katalon/media
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  admin:
+    image: {{ registry }}-web:{{ version }}
+    restart: unless-stopped
+    environment:
+      KATALON_WEB_MODE: admin
+
+  portal:
+    image: {{ registry }}-web:{{ version }}
+    restart: unless-stopped
+    environment:
+      KATALON_WEB_MODE: portal
+
+{% if tls_mode == "standalone" %}
+  proxy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    environment:
+      KATALON_BASE_URL: {{ base_url }}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+    depends_on:
+      - api
+      - admin
+      - portal
+{% elif tls_mode == "behind-proxy" %}
+  proxy:
+    image: nginx:alpine
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8080:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+    depends_on:
+      - api
+      - admin
+      - portal
+{% endif %}
+
+volumes:
+  db_data:
+  es_data:
+{% if tls_mode == "standalone" %}
+  caddy_data:
+{% endif %}