ConvertX 2026 selbst hosten: Uploads, JWT-Secrets und Ressourcenlimits

Es gibt zwei Varianten, „ConvertX zu betreiben“: Entweder existiert ein Container, oder der Dienst erledigt seine eigentliche Aufgabe. Nur die zweite Variante zählt. Der Nachweis besteht darin, mehrere repräsentative Formate hochzuladen, jedes davon zu konvertieren, die Ergebnisse herunterzuladen und – sofern deterministisch – Hashes oder Medieneigenschaften zu vergleichen.

ConvertX dient genau diesem Zweck: als browserbasierter Dienst zur Dateikonvertierung. Das Deployment muss die Komponenten hinter diesem Verhalten zuverlässig bereitstellen. Ein Port, ein Volume und ein Zertifikat sind Voraussetzungen, aber noch kein Ergebnis.

Die kleinstmögliche tragfähige ConvertX-Topologie wählen

Beginne mit dem Netzwerk-Namespace von ConvertX: Der Web-Listener verwendet Port 3000 und nicht etwa einen Host-Port, der aus einem Laptop-Tutorial übernommen wurde. Die Anforderungen an die lokale Laufzeitumgebung sind CPU, Arbeitsspeicher und temporärer Speicher, passend zu den ausgewählten Convertern. Dokumentiere die erwartete Kapazität, die Besitzverhältnisse und das Fehlerverhalten, statt diese Punkte dem Image-Default zu überlassen.

Sobald die Anforderungen erfüllt sind, führe das vollständige Szenario aus: mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen. Erfasse Logs und Messwerte für CPU, Arbeitsspeicher, temporären Speicher, Dateigröße und die Converter-Binaries, die für jedes Formatpaar aufgerufen werden. Diese Belege bilden die erste nachweislich funktionierende Architektur und machen spätere Umzüge zwischen Dockup-Compute und einem angebundenen Server testbar.

Interne und externe URLs richtig auseinanderhalten

Vermeide temporäre und dauerhafte öffentliche Origins für ConvertX. Veröffentliche die UI stattdessen über HTTPS mit bewusst festgelegten Upload-Limits, richte den ausgewählten DNS-Namen auf die Plattform-Route und proxye ausschließlich auf Port 3000.

Führe diesen Vorgang von außerhalb des Hosts aus: mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen. Falls der Ingress fehlschlägt, behandelt der Leitfaden zur Fehlerbehebung bei 502 Bad Gateway Fehler bei Ports und Listenern. Wenn ConvertX die Anfrage empfängt, aber ein Converter-Binary fehlt oder der Proxy einen großen Upload ablehnt, weisen die Belege nun auf eine Ursache jenseits des Proxys hin.

Container-Einstellungen, die du prüfen solltest

Starte ConvertX so, dass die Route privat bleibt, bis das Bootstrap abgeschlossen ist.

docker run -d \
  --name convertx \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v convertx-data:/app/data \
  -e JWT_SECRET=replace-with-a-long-random-value \
  ghcr.io/c4illin/convertx:latest

Wenn der Prozess in einer Schleife läuft, vergleiche den vom Image erwarteten Benutzer mit dem Eigentümer jedes eingebundenen Pfads. Wenn der Prozess aktiv bleibt, teste Port 3000 lokal und gehe anschließend direkt zum Workflow über: mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen. Pinne die Image-Version erst fest, wenn dieser End-to-End-Check erfolgreich ist, und dokumentiere die exakte Konfiguration neben dem Dienst.

Die riskante ConvertX-Änderung proben

Ein inaktiver Healthcheck sagt über ConvertX nur wenig aus. Beobachte CPU, Arbeitsspeicher, temporären Speicher, Dateigröße und die Converter-Binaries, die für jedes Formatpaar aufgerufen werden. Löse anschließend anhand des Symptoms aus, das Benutzer tatsächlich erleben: dem Fehlschlagen der Aktion „mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen“. Halte den Liveness-Check lokal und kostengünstig. Die Readiness sollte Migrationen oder Initialisierung melden, ohne eine Restart-Schleife auszulösen.

Der kritische Bereich bei Upgrades besteht darin, dass Image-Releases Converter hinzufügen oder entfernen können. Teste daher exakt die Formatmatrix, auf die deine Benutzer angewiesen sind. Lies die Release Notes, erstelle einen Snapshot des Zustands, deploye die Zielversion gegen eine wiederhergestellte Kopie und wiederhole den Abnahmetest. Wenn ein Converter-Binary fehlt oder der Proxy einen großen Upload ablehnt, ordne die Client-Anfrage dem ersten relevanten Application-Log zu, statt blind den Zustand zu löschen oder zusätzliche Redirects einzurichten.

Fünf aussagekräftigere Checks als der Container-Healthcheck

Mache den Traffic des ersten Benutzers nicht zum Abnahmetest für ConvertX. Bereite unkritische Beispieldaten vor und führe die vollständige Aktion aus: „mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen“. Notiere die exakte öffentliche URL, das Ergebnis, die Image-Referenz und das zugehörige Log-Zeitfenster.

Ersetze den Container und wiederhole den Test, ohne die Daten neu aufzubauen. Stelle den Dienst anschließend auf einem leeren Host wieder her. Die Wiederherstellungsbedingung ist erfüllt, wenn Konten und Einstellungen zurückkehren und die feste Formatmatrix innerhalb der festgelegten Limits weiterhin erfolgreich verarbeitet wird. Beobachte bei jedem Durchlauf CPU, Arbeitsspeicher, temporären Speicher, Dateigröße und die Converter-Binaries, die für jedes Formatpaar aufgerufen werden. Definiere den Alert anhand einer Verschlechterung der Transaktion und nicht anhand von Metriken eines inaktiven Containers.

Ein letzter Check sollte absichtlich fehlschlagen: Sende eine unkritische Eingabe nahe am Ressourcen- oder Formatlimit dieser Grenze – ein Converter-Binary fehlt oder der Proxy lehnt einen großen Upload ab. Prüfe, dass die resultierende ConvertX-Meldung die relevante Grenze nennt, statt eine Datenlöschung oder einen endlosen Neustart auszulösen. Stelle den gültigen Zustand wieder her und bestätige, dass dieselbe Beispieltransaktion erfolgreich ist. Nimm diese kurze Übung in die Release-Checkliste auf.

Jedes dauerhafte Byte in ConvertX finden

Zum dauerhaft zu sichernden Wiederherstellungsumfang gehören Anwendungsdaten, Konten und alle gespeicherten Konvertierungseinstellungen. Binde /app/data vor dem Bootstrap ein, schreibe unkritische Beispieldaten und ersetze den Container, um zu beweisen, dass dieser Pfad tatsächlich persistent ist. Ein Volume schützt Daten vor dem Ersetzen des Containers, aber nicht vor dem Verlust des Hosts, versehentlichem Löschen oder Beschädigungen auf Anwendungsebene.

Erstelle Backups mit einem Verfahren, das die Datenquelle berücksichtigt: Verwende bei Bedarf logische Dumps für laufende Datenbanken und kopiere Dateien nur aus einem konsistenten Zustand. Bewahre eine verschlüsselte Kopie außerhalb des ConvertX-Hosts auf. Das Abnahmekriterium für eine Wiederherstellung muss konkret sein: Konten und Einstellungen kehren zurück und die feste Formatmatrix wird innerhalb der festgelegten Limits weiterhin erfolgreich verarbeitet. Der Leitfaden für Wiederherstellungs-getestete Backups erklärt, warum ein erfolgreicher Job allein nicht ausreicht.

Die von ConvertX gehaltenen Berechtigungen reduzieren

Prüfe nach dem ersten Login, welche Aktionen anonyme Besucher, normale Benutzer und Administratoren jeweils ausführen können. Ein zu vermeidender ConvertX-Fehler ist die Verwendung eines Beispiel-JWT-Secrets oder das Anbieten uneingeschränkter öffentlicher Konvertierungen. Die vorgesehene Richtlinie lautet: ein echtes JWT-Secret verwenden, einen Login voraussetzen und Uploads begrenzen, bevor nicht vertrauenswürdige Dateien aus dem Internet akzeptiert werden.

Erzeuge JWT_SECRET als langen Zufallswert. Eine Rotation macht Sessions oder Tokens normalerweise ungültig. Plane daher die Auswirkungen auf Benutzer ein, statt sie als Verschlüsselungsmigration zu behandeln. Halte Konten für Abhängigkeiten von menschlichen Konten getrennt, untersage nicht benötigten ausgehenden Traffic, soweit praktikabel, und begrenze die Arbeit, die durch CPU, Arbeitsspeicher, temporären Speicher, Dateigröße und die für jedes Formatpaar aufgerufenen Converter-Binaries beeinflusst wird.

ConvertX auf Dockup deployen, ohne seine Grenzen aufzugeben

Dockup nimmt dir die manuelle Arbeit rund um Reverse-Proxy und Lifecycle von ConvertX ab. Der Dienst erhält während des Ersetzens eine stabile HTTPS-Route zu Port 3000, injizierte Konfiguration und persistenten Speicher. Ein angebundener Kundenserver folgt demselben Modell wie von Dockup gehostete Compute-Ressourcen.

Erfülle nach dem Start den Application Contract: Veröffentliche die UI über HTTPS mit bewusst festgelegten Upload-Limits, bestätige die lokale Anforderung – CPU, Arbeitsspeicher und temporären Speicher passend zu den ausgewählten Convertern – und führe diesen Nachweis aus: mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen. So bleibt die One-Click-Erfahrung nützlich, ohne die Details zu vereinfachen, die ConvertX wiederherstellbar und sicher machen.

Häufig gestellte Fragen

Was benötigt ConvertX für ein produktives Deployment?

Leite den ConvertX-Container über einen einzigen HTTPS-Origin auf Port 3000 weiter. Die Anforderungen an die lokale Laufzeitumgebung sind CPU, Arbeitsspeicher und temporärer Speicher, passend zu den ausgewählten Convertern. Erkläre ConvertX erst dann für einsatzbereit, wenn du mehrere repräsentative Formate hochladen, jedes davon konvertieren, die Ergebnisse herunterladen und – sofern deterministisch – Hashes oder Medieneigenschaften vergleichen kannst.

Welche ConvertX-Daten gehören in ein Backup?

Mache /app/data persistent und nimm Anwendungsdaten, Konten sowie alle gespeicherten Konvertierungseinstellungen in dasselbe Wiederherstellungsmanifest auf. Eine saubere ConvertX-Wiederherstellung ist erst dann erfolgreich, wenn Konten und Einstellungen zurückkehren und die feste Formatmatrix innerhalb der festgelegten Limits weiterhin erfolgreich verarbeitet wird.

Benötigt ConvertX hinter einem Reverse-Proxy HTTPS?

Verwende HTTPS für den öffentlichen ConvertX-Origin und belasse Port 3000 auf der internen Route. Setze die ConvertX-Einstellung korrekt: Veröffentliche die UI über HTTPS mit bewusst festgelegten Upload-Limits. Bei ConvertX schützt HTTPS Zugangsdaten und Benutzerinhalte während der Übertragung und sorgt für ein konsistentes Client-Verhalten, das vom Origin abhängt.

Wie sollte ein ConvertX-Upgrade getestet werden?

Stelle den aktuellen ConvertX-Zustand in einem isolierten Deployment wieder her, wende die Kandidatenversion an und wiederhole die Abnahmetransaktion. Achte besonders darauf, dass Image-Releases Converter hinzufügen oder entfernen können. Teste daher exakt die Formatmatrix, auf die deine Benutzer angewiesen sind. Bewahre das vorherige ConvertX-Image auf, bis die Grenzen für Datenmigration und Rollback verstanden sind.