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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: katalon-cli
-Version: 0.2.1
+Version: 0.3.1
 Summary: Installer & Updater CLI für Katalon Production-Instanzen
 Author: Karl Krägelin
 Author-email: Karl Krägelin <karlkraegelin@gmail.com>
@@ -83,6 +83,31 @@ unter `MEDIA_ROOT`, die noch einem anderen Eigentümer gehören. Dateiinhalte we
 verändert; ein erneuter Lauf ändert nichts. `katalon doctor` meldet ein nicht beschreibbares
 `MEDIA_ROOT`, bevor Uploads mit HTTP 500 scheitern.
 
+## Bild-Cache (Cantaloupe)
+
+Vorschaubilder und Viewer-Kacheln rechnet Cantaloupe aus den Originalen und legt sie im
+Instanzverzeichnis unter `cantaloupe-cache/` ab (abweichend: `CANTALOUPE_CACHE_DIR` in `.env`).
+Der Cache übersteht Neustarts und Updates; ein kurzlebiger Init-Container übergibt das
+Verzeichnis vor jedem Start dem Cantaloupe-User. Abgelaufene Derivate
+(`CANTALOUPE_CACHE_SERVER_DERIVATIVE_TTL_SECONDS`, Standard 30 Tage) löscht Cantaloupe selbst.
+
+Eine Größenbegrenzung kennt Cantaloupe nicht. Als Richtwert ~25 KB pro Vorschaubild plus
+Kacheln der aufgerufenen Detailansichten einplanen; wer den Platz hart begrenzen muss, legt
+`CANTALOUPE_CACHE_DIR` auf ein eigenes Dateisystem bzw. Quota-Verzeichnis. Hosts ohne
+Plattenplatz nutzen mit `CANTALOUPE_FILESYSTEMCACHE_PATHNAME=/tmpfs/cache` einen RAM-Cache
+(`CANTALOUPE_CACHE_TMPFS_SIZE`, Standard `512m`), der nach jedem Neustart leer ist.
+
+Vorschaubilder lassen sich vorab berechnen, damit schon der erste Aufruf der Trefferliste
+schnell ist: `katalon media warm-thumbnails` (Hauptbilder zuerst, dann die übrigen; mit
+`--primary-only` nur Hauptbilder, `--status` zeigt den Fortschritt). Der Lauf arbeitet im
+Worker in kleinen Paketen, belegt höchstens `THUMBNAIL_WARM_CONCURRENCY` (Standard 3)
+Cantaloupe-Kerne und setzt nach einer Unterbrechung beim letzten Stand fort. Neu hochgeladene
+Bilder werden automatisch vorberechnet.
+
+Bestehende Instanzen stellt `katalon update` automatisch um (neue `compose.yaml`); der bisherige
+RAM-Cache entfällt dabei. Releases, die eine neuere CLI voraussetzen, bricht `katalon update`
+mit einem Hinweis auf `uv tool upgrade katalon-cli` ab.
+
 ## Domain und HTTPS
 
 Für eine lokale Installation bleibt `http://localhost` mit TLS-Modus `none` der Standard.

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

@@ -69,6 +69,31 @@ unter `MEDIA_ROOT`, die noch einem anderen Eigentümer gehören. Dateiinhalte we
 verändert; ein erneuter Lauf ändert nichts. `katalon doctor` meldet ein nicht beschreibbares
 `MEDIA_ROOT`, bevor Uploads mit HTTP 500 scheitern.
 
+## Bild-Cache (Cantaloupe)
+
+Vorschaubilder und Viewer-Kacheln rechnet Cantaloupe aus den Originalen und legt sie im
+Instanzverzeichnis unter `cantaloupe-cache/` ab (abweichend: `CANTALOUPE_CACHE_DIR` in `.env`).
+Der Cache übersteht Neustarts und Updates; ein kurzlebiger Init-Container übergibt das
+Verzeichnis vor jedem Start dem Cantaloupe-User. Abgelaufene Derivate
+(`CANTALOUPE_CACHE_SERVER_DERIVATIVE_TTL_SECONDS`, Standard 30 Tage) löscht Cantaloupe selbst.
+
+Eine Größenbegrenzung kennt Cantaloupe nicht. Als Richtwert ~25 KB pro Vorschaubild plus
+Kacheln der aufgerufenen Detailansichten einplanen; wer den Platz hart begrenzen muss, legt
+`CANTALOUPE_CACHE_DIR` auf ein eigenes Dateisystem bzw. Quota-Verzeichnis. Hosts ohne
+Plattenplatz nutzen mit `CANTALOUPE_FILESYSTEMCACHE_PATHNAME=/tmpfs/cache` einen RAM-Cache
+(`CANTALOUPE_CACHE_TMPFS_SIZE`, Standard `512m`), der nach jedem Neustart leer ist.
+
+Vorschaubilder lassen sich vorab berechnen, damit schon der erste Aufruf der Trefferliste
+schnell ist: `katalon media warm-thumbnails` (Hauptbilder zuerst, dann die übrigen; mit
+`--primary-only` nur Hauptbilder, `--status` zeigt den Fortschritt). Der Lauf arbeitet im
+Worker in kleinen Paketen, belegt höchstens `THUMBNAIL_WARM_CONCURRENCY` (Standard 3)
+Cantaloupe-Kerne und setzt nach einer Unterbrechung beim letzten Stand fort. Neu hochgeladene
+Bilder werden automatisch vorberechnet.
+
+Bestehende Instanzen stellt `katalon update` automatisch um (neue `compose.yaml`); der bisherige
+RAM-Cache entfällt dabei. Releases, die eine neuere CLI voraussetzen, bricht `katalon update`
+mit einem Hinweis auf `uv tool upgrade katalon-cli` ab.
+
 ## Domain und HTTPS
 
 Für eine lokale Installation bleibt `http://localhost` mit TLS-Modus `none` der Standard.

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

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

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

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

{katalon_cli-0.2.1 → katalon_cli-0.3.1}/src/katalon_cli/core/checks.py

@@ -26,6 +26,8 @@ def check_docker() -> CheckResult:
 
 
 def check_compose() -> CheckResult:
+    if not shutil.which("docker"):
+        return CheckResult("Docker Compose", False, "Docker fehlt")
     probe = subprocess.run(["docker", "compose", "version"], capture_output=True, text=True)
     if probe.returncode == 0:
         return CheckResult("Docker Compose", True, probe.stdout.strip())

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

@@ -456,6 +456,21 @@ def _media_root(dir: Path) -> str:
     return str(path if path.is_absolute() else dir / path)
 
 
+def _require_installer_version(minimum: str) -> None:
+    """Bricht ab, wenn das Release eine neuere CLI braucht (z. B. neues Compose-Template).
+
+    Sonst würde eine alte CLI ihr altes compose.yaml-Template schreiben und das Release
+    liefe ohne die Topologie, für die es gebaut ist."""
+    current = version("katalon-cli")
+    if selfupdate.is_newer(minimum, current):
+        console.print(
+            f"[red]✖ Dieses Release braucht katalon-cli ≥ {minimum} (installiert: {current}).[/]\n"
+            "  Zuerst aktualisieren: [bold]uv tool upgrade katalon-cli[/], dann erneut "
+            "[bold]katalon update[/]."
+        )
+        raise typer.Exit(1)
+
+
 def _ensure_media_permissions(dir: Path) -> bool:
     """Macht MEDIA_ROOT für den Container-User von API/Worker beschreibbar (idempotent).
 
@@ -475,6 +490,9 @@ def _ensure_media_permissions(dir: Path) -> bool:
 
 
 def _start(dir: Path, show_credentials: bool = False) -> None:
+    # Ohne capture: Fortschritt sichtbar, sonst wirkt der erste Image-Pull wie ein Hänger.
+    console.print("Lade Images (beim ersten Start einige Minuten) …")
+    docker.compose(dir, "pull")
     _ensure_media_permissions(dir)
     docker.compose(dir, "up", "-d")
     console.print("[green]✔[/] Stack gestartet.")
@@ -559,6 +577,32 @@ def manage(
     raise typer.Exit(result.returncode)
 
 
+media_app = typer.Typer(no_args_is_help=True, help="Medien: Vorschaubilder vorberechnen.")
+app.add_typer(media_app, name="media")
+
+
+@media_app.command("warm-thumbnails")
+def media_warm_thumbnails(
+    dir: Path | None = typer.Option(None, "--dir"),
+    primary_only: bool = typer.Option(False, "--primary-only", help="Nur das Hauptbild jedes Objekts."),
+    restart: bool = typer.Option(False, "--restart", help="Von vorn beginnen statt fortsetzen."),
+    status: bool = typer.Option(False, "--status", help="Nur den Fortschritt anzeigen."),
+):
+    """Vorschaubilder im Cantaloupe-Cache vorberechnen (läuft im Worker, fortsetzbar).
+
+    Sinnvoll nach Installation, Massenimport oder Umstellung des Bild-Caches."""
+    dir = instance_dir_or_raise(dir)
+    args = ["warm-thumbnails"]
+    if primary_only:
+        args.append("--primary-only")
+    if restart:
+        args.append("--restart")
+    if status:
+        args.append("--status")
+    result = docker.compose(dir, "exec", "api", "katalon-manage", *args, check=False)
+    raise typer.Exit(result.returncode)
+
+
 def _ensure_db_running(dir: Path, yes: bool = False) -> None:
     if docker.is_running(dir, "db"):
         return
@@ -630,6 +674,7 @@ def check_updates(dir: Path | None = typer.Option(None, "--dir")):
     if meta.version == state.version:
         console.print(f"[green]✔[/] Bereits auf aktueller Version {meta.version}.")
         return
+    _require_installer_version(meta.minimum_installer_version)
     console.print(f"Update verfügbar: [bold]{state.version}[/] → [bold]{meta.version}[/]")
 
 

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

@@ -39,15 +39,31 @@ services:
       timeout: 10s
       retries: 20
 
+  # Legt den Derivat-Cache an und übergibt ihn dem Cantaloupe-User des Images.
+  # Ändert nur Einträge mit falschem Eigentümer (idempotent, schnell bei vollem Cache).
+  cantaloupe-cache-init:
+    image: islandora/cantaloupe:main
+    user: "0:0"
+    entrypoint: ["sh", "-c", "mkdir -p /data/cache && find /data ! -user cantaloupe -exec chown cantaloupe:cantaloupe {} +"]
+    volumes:
+      - ${CANTALOUPE_CACHE_DIR:-./cantaloupe-cache}:/data
+    restart: "no"
+
   cantaloupe:
     image: islandora/cantaloupe:main
     restart: unless-stopped
     volumes:
       - ${MEDIA_ROOT:-./media}:/var/lib/cantaloupe/images:ro
+      # Derivat-Cache auf Platte, übersteht Neustarts. Ohne Plattenplatz:
+      # CANTALOUPE_FILESYSTEMCACHE_PATHNAME=/tmpfs/cache in .env (RAM, leer nach Neustart).
+      - ${CANTALOUPE_CACHE_DIR:-./cantaloupe-cache}:/data
       - type: tmpfs
-        target: /var/lib/cantaloupe/cache
+        target: /tmpfs
         tmpfs:
           size: ${CANTALOUPE_CACHE_TMPFS_SIZE:-512m}
+          mode: 1023  # = 0o1777 (Compose liest den Wert dezimal)
+    depends_on:
+      cantaloupe-cache-init: { condition: service_completed_successfully }
     environment:
       CANTALOUPE_SOURCE_STATIC: FilesystemSource
       CANTALOUPE_FILESYSTEMSOURCE_LOOKUP_STRATEGY: BasicLookupStrategy
@@ -55,10 +71,19 @@ services:
       CANTALOUPE_BASE_URI: ${CANTALOUPE_PUBLIC_URL:-http://localhost}
       CANTALOUPE_CACHE_SERVER_DERIVATIVE: FilesystemCache
       CANTALOUPE_CACHE_SERVER_DERIVATIVE_ENABLED: "true"
-      CANTALOUPE_FILESYSTEMCACHE_PATHNAME: /var/lib/cantaloupe/cache
+      CANTALOUPE_FILESYSTEMCACHE_PATHNAME: ${CANTALOUPE_FILESYSTEMCACHE_PATHNAME:-/data/cache}
+      # Der Cache-Worker löscht Derivate älter als die TTL; ohne ihn wächst der Cache unbegrenzt.
+      CANTALOUPE_CACHE_SERVER_WORKER_ENABLED: "true"
+      CANTALOUPE_CACHE_SERVER_DERIVATIVE_TTL_SECONDS: ${CANTALOUPE_CACHE_SERVER_DERIVATIVE_TTL_SECONDS:-2592000}
       CANTALOUPE_PROCESSOR_MANUALSELECTIONSTRATEGY_JPG: Java2dProcessor
+      # Fallback ohne nginx davor: nie "public". nginx setzt Cache-Control für /iiif/
+      # nach Sichtbarkeit (X-Media-Visibility aus /v1/media/_authorize).
+      CANTALOUPE_CACHE_CLIENT_PUBLIC: "false"
+      CANTALOUPE_CACHE_CLIENT_PRIVATE: "true"
     healthcheck:
-      test: ["CMD-SHELL", "curl -sf http://localhost:8182/iiif/3"]
+      # Prüft neben der Erreichbarkeit, dass der Cantaloupe-Prozess in seinen Cache
+      # schreiben kann — sonst liefert er Bilder mit 0 Bytes bei HTTP 200.
+      test: ["CMD-SHELL", "curl -sf http://localhost:8182/iiif/3 && runuser -u cantaloupe -- sh -c 'd=$${CANTALOUPE_FILESYSTEMCACHE_PATHNAME:-/data/cache}; mkdir -p \"$$d\" && touch \"$$d/.healthcheck\" && rm -f \"$$d/.healthcheck\"'"]
       interval: 10s
       timeout: 5s
       start_period: 300s

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

@@ -1,5 +1,13 @@
 resolver 127.0.0.11 valid=10s ipv6=off;
 
+# Cache-Control for /iiif/ from the media's visibility (set by /v1/media/_authorize via
+# auth_request_set): shared caches (CDN, proxies) may keep only what anonymous
+# visitors may see; derivatives of internal media stay in the requesting browser.
+map $media_visibility $iiif_cache_control {
+    public  "public, max-age=2592000";
+    default "private, max-age=86400";
+}
+
 server {
 {% if tls_mode == "standalone" %}
     listen 80;
@@ -73,12 +81,22 @@ server {
 
     location /iiif/ {
         auth_request /internal/media-authorize;
+        auth_request_set $media_visibility $upstream_http_x_media_visibility;
         set $upstream_cantaloupe cantaloupe:8182;
         proxy_pass http://$upstream_cantaloupe;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_read_timeout 300s;
         proxy_buffering off;
+        # Cantaloupe marks every derivative public; decide by visibility instead.
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control $iiif_cache_control;
+        # An add_header here drops the server-level ones: repeat them.
+        add_header Content-Security-Policy "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob: https:; media-src 'self' blob: https:; connect-src 'self' https:; frame-src 'self' https://www.openstreetmap.org; worker-src 'self' blob:" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header Permissions-Policy "camera=(), geolocation=(), microphone=()" always;
     }
 
     location = /internal/media-authorize {