katalon-cli
Installer & Updater für Katalon Collections 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
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install katalon-cli
Nutzung
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.
katalon install --dir ~/meine-katalon-instanz
katalon start
katalon status
Images der Fremdservices
Welche Images Postgres, Redis, Elasticsearch, Cantaloupe, nginx und Caddy nutzen, legt das
Katalon-Release fest (images in katalon-release.json), nicht die CLI. install und update
schreiben sie in compose.yaml, update pullt sie mit. Releases ohne images (bis Katalon
1.46.0) bekommen die Images, die bis katalon-cli 0.3.5 fest im Template standen.
Vor einem Update vergleicht katalon update die wirksamen Images (inklusive
compose.override.yaml) vor und nach dem Update, zeigt jeden Wechsel an und bricht ab, bevor
etwas geändert wird, wenn
- Postgres oder Elasticsearch die Major-Version wechseln würden (Postgres braucht dafür Dump/Restore, Elasticsearch ein neues Datenverzeichnis und einen Reindex), oder
- ein Postgres- oder Elasticsearch-Image die Anforderung des Releases (
requires, z. B.>=8.13,<9) nicht erfüllt, etwa ein eigenes Image auscompose.override.yaml.requiresgilt erst ab Releases mitimages; ältere Releases nannten dort Werte, die nie geprüft wurden.
installation.json merkt sich die Images je Version. rollback nimmt die der vorigen Version,
behält aber ein neueres Elasticsearch derselben Major-Version, weil Elasticsearch ein
Datenverzeichnis nicht mit einer älteren Version öffnet.
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.
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.
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-Volumescaddy_dataundcaddy_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/alsfullchain.pemundprivkey.pemabgelegt 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 auf127.0.0.1:8080erreichbar.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 beschrieben.
Die CLI erzeugt <dir>/Caddyfile bei Installation, Update und Rollback neu;
instanzspezifische Compose-Anpassungen gehören in compose.override.yaml.
Entwicklung
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.jsonAsset). Enthält optionalenv_vars/deprecated_env_vars:install/updateergänzen neue Pflichtvariablen automatisch (Secret generieren oder Default übernehmen), fragen bei fehlendem Default interaktiv nach (--yesbricht dann ab), tragen neue optionale Variablen auskommentiert in.envein und warnen vor veralteten Variablen, die noch in der.envstehen.core/compose_gen.py+templates/compose.yaml.j2+templates/nginx.conf.j2— rendertcompose.yamlnginx.confund beitls_mode=caddydasCaddyfileaus Version, Images + TLS-Modus; erzeugt beitls_mode=standaloneein selbstsigniertes Zertifikat unter<dir>/certs/(eigenes Zertifikat dort ablegen, um es zu ersetzen).installfragt zusätzlichMEDIA_ROOTab und legt<dir>/compose.override.yaml.examplean (instanzspezifische Overrides — umbenennen zucompose.override.yaml, wird automatisch eingebunden und bei Updates nicht angefasst). Optionale Env-Vars (Admin-Login, SMTP, Geonames, …) landet auskommentiert in.env.
core/images.py— prüft die Images der Fremdservices vor einem Update (siehe „Images der Fremdservices“).core/backup.py—pg_dumpvor jedem Update; Rollback restauriert Dump stattalembic downgrade.core/docker.py— dünnerdocker compose-Subprocess-Wrapper.main.py— Typer-Commands, interaktive Teile überrich.prompt/rich.progress.
Metadata
Release files for katalon-cli 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| katalon_cli-0.5.0.tar.gz | 35.3 kB | With provenance | Details for katalon_cli-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| katalon_cli-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for katalon_cli-0.5.0-py3-none-any.whl |
Total release size: 76.8 kB
Release files / katalon_cli-0.5.0.tar.gz
| Download URL | katalon_cli-0.5.0.tar.gz |
|---|---|
| Size | 35.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6051cb6ab451c99db1ab13961a5e84fa5af3bba4d59c530273480805729e8702
|
|
BLAKE2b-256 checksum How to use checksums |
19acc751ae6e8af99aad4587e811c69c625b457cfb5470be4458cade515bf45b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / katalon_cli-0.5.0-py3-none-any.whl
| Download URL | katalon_cli-0.5.0-py3-none-any.whl |
|---|---|
| Size | 41.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1834414104b1542a8cedd849717461c35e270d669a292390ca233e5845b4f566
|
|
BLAKE2b-256 checksum How to use checksums |
230e99b8e68c5e72834446ef10f4943fba06372b1671efe9f76f53909ea33bcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for katalon-cli 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for katalon_cli-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.