Satis auf Coolify deployen: Private Composer-Registry mit automatischen Builds (Docker, PHP)

Warum dieses Repo? Private Composer-Packages ohne eigenes „Platform-Team“

Viele Teams haben interne PHP-Bibliotheken oder Kunden-spezifische Packages, die nicht öffentlich auf Packagist landen sollen. Gleichzeitig möchte man die gewohnte Composer-UX behalten: composer require vendor/package, Versionen über Git-Tags, und eine zentrale Quelle für Abhängigkeiten. Genau hier setzt das Repo satis-coolify an: Es kombiniert Satis (statisches Composer-Repository) mit einem Docker-basierten Deployment auf Coolify – inklusive automatischen Builds und Token-Authentifizierung.

Der Fokus liegt auf einem pragmatischen Setup: Du verknüpfst das Git-Repository in Coolify, setzt ein paar Environment-Variablen, und nach wenigen Minuten steht eine private Paketquelle bereit. Wichtig: Der erste Build dauert typischerweise 3–5 Minuten, weil Satis initial installiert und der Index aufgebaut wird.

Architektur in einem Satz: Builder + Nginx, gesteuert über Environment-Variablen

Das Repo bringt ein docker-compose.yml mit, das zwei Rollen abbildet: einen Builder, der Satis regelmäßig ausführt und den Output erzeugt, sowie einen Webserver (Nginx), der den generierten Output ausliefert. Die Satis-Konfiguration wird nicht manuell in Dateien gepflegt, sondern über Environment-Variablen (z. B. Name, Homepage, Repositories) generiert. Das ist besonders praktisch in Coolify, weil du dort Konfiguration und Secrets zentral verwaltest.

Voraussetzungen und Vorüberlegungen

• Coolify mit der Möglichkeit, eine „Docker Compose“-Applikation zu deployen.
• Eine Domain oder Subdomain, z. B. packages.your-domain.com, die du in Coolify der App zuweist.
• GitHub-Repositories mit deinen Composer-Packages (öffentlich oder privat). Für private Repos ist ein GITHUB_TOKEN zwingend.
• Ein Plan für Authentifizierung: Das Repo unterstützt Token-basierten Zugriff. Ohne ACCESS_TOKEN ist das Repository laut README öffentlich – das ist ein zentraler Sicherheitsaspekt.

Schritt-für-Schritt: Deployment in Coolify

1) Neue Docker-Compose-App in Coolify anlegen

In Coolify erstellst du eine neue Anwendung vom Typ Docker Compose. Danach verknüpfst du das Git-Repository: https://github.com/alandolsi/satis-coolify. Coolify zieht sich die Compose-Datei und baut/started die Services entsprechend.

2) Domain setzen und SSL aktivieren

Lege als Domain z. B. packages.your-domain.com fest. In Coolify kannst du SSL in der Regel direkt aktivieren. Achte darauf, dass die Domain später exakt zu deiner Composer-Konfiguration passt (inklusive https), weil Composer sehr empfindlich auf URL-Abweichungen reagiert.

3) Environment-Variablen korrekt setzen (kritischer Teil)

Die README definiert die erforderlichen Variablen. Die wichtigsten sind:

• GITHUB_TOKEN: erforderlich für private Repositories (und generell empfehlenswert wegen Rate Limits).
• ACCESS_TOKEN: schützt dein Repository. Ohne diesen Token ist der Zugriff nicht eingeschränkt.
• SATIS_REPOSITORIES: JSON-Array mit deinen VCS-Repositories. Das ist die häufigste Fehlerquelle.
• SATIS_HOMEPAGE: sollte auf deine Domain zeigen (https://packages.your-domain.com).
• SATIS_BUILD_INTERVAL: Standard 900 Sekunden (15 Minuten). Optional.

Ein realistisches Minimal-Set (als Orientierung) sieht so aus:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

ACCESS_TOKEN=your-secure-random-token-here

SATIS_BUILD_INTERVAL=900

SATIS_NAME=your-vendor/packages

SATIS_HOMEPAGE=https://packages.your-domain.com

SATIS_DESCRIPTION=Private Composer Package Repository

SATIS_REPOSITORIES=[{"type":"vcs","url":"https://github.com/YOUR-USERNAME/package-one.git"},{"type":"vcs","url":"https://github.com/YOUR-USERNAME/package-two.git"}]

Caveat 1: SATIS_REPOSITORIES muss gültiges JSON sein. Tipp aus der README: Coolify erlaubt Multiline-Variablen („Is Multiline“). Das Repo bereinigt Whitespace automatisch, sodass auch formatiertes JSON funktionieren kann. Trotzdem solltest du bei Problemen zuerst testen, ob dein JSON wirklich valide ist (z. B. fehlende Kommas, falsche Quotes).

Caveat 2: Platzhalter sind echte Fehler. Ein Klassiker ist, dass noch YOUR-USERNAME oder Beispiel-URLs in SATIS_REPOSITORIES stehen. Das führt später zu 404s oder dazu, dass keine Packages erscheinen.

4) GitHub Token erstellen (für private Repos)

Wenn du private Repositories indexieren willst, brauchst du ein GitHub Token mit passenden Rechten. Die README nennt den Weg: https://github.com/settings/tokens/new?scopes=repo und Scope repo (Full control of private repositories). Hinterlege den Token als GITHUB_TOKEN in Coolify.

Caveat: Ein ungültiger oder fehlender Token führt nicht nur zu Auth-Problemen, sondern auch zu Rate Limits bei der GitHub API. Das äußert sich oft als „Build läuft, aber findet nichts“ oder als sehr langsame Builds.

5) Deploy auslösen und den ersten Build abwarten

Starte das Deployment in Coolify. Plane für den ersten Lauf 3–5 Minuten ein. In dieser Phase wird Satis initialisiert und der erste Index gebaut. Erst danach ist die Weboberfläche bzw. der Composer-Endpunkt sinnvoll nutzbar.

Composer-Projekte anbinden (empfohlen: Bearer Token)

Wenn die Domain erreichbar ist, bindest du das Repository in deinen Projekten ein. Die README empfiehlt Bearer Token – das ist in der Praxis sauberer als Query-Parameter, weil Tokens nicht so leicht in Logs/Proxies auftauchen.

Beispiel für composer.json (Token und Domain anpassen):

composer require vendor/package-name

Die eigentliche Composer-Konfiguration aus der README sieht so aus (hier als Inhalt, den du in composer.json einfügst):

# In composer.json unter "config" und "repositories" eintragen (siehe README)

Caveat: Achte darauf, dass die Domain in der Bearer-Konfiguration exakt der Hostname ist (ohne https://), während die Repository-URL typischerweise mit https:// angegeben wird. Wenn du dich vertippst, wirkt es so, als wäre das Repository „kaputt“, dabei wird nur der Token nicht mitgesendet.

Neue Packages hinzufügen: nur SATIS_REPOSITORIES erweitern

Der Workflow ist bewusst simpel: Du ergänzt in Coolify die Variable SATIS_REPOSITORIES um ein weiteres Objekt und redeployst. Die README zeigt zwei Varianten:

• Kompakt (eine Zeile) – weniger Fehlerquellen bei Copy/Paste.
• Formatiert (Multiline) – besser lesbar, wenn du viele Repos hast.

Nach dem Speichern: Redeploy und dann typischerweise 2–3 Minuten warten, bis das neue Package im Index auftaucht.

Versionen und Updates: Tags sind der Schlüssel

Satis arbeitet versionsorientiert: Es scannt deine Repositories und nimmt Versionen typischerweise über Git-Tags auf. Das Repo ist auf automatische Builds alle 15 Minuten ausgelegt (Standard: 900 Sekunden). Wenn eine neue Version nicht erscheint, ist die Ursache in der Praxis meist eine dieser:

• Tag existiert lokal, wurde aber nicht gepusht.
• Build-Intervall noch nicht erreicht (einfach warten).
• GitHub Token fehlt/ist ungültig → Rate Limits oder Auth-Probleme.
• Repository-URL falsch oder Repo nicht erreichbar.

Manuellen Build triggern (Debug-freundlich)

Wenn du nicht warten willst oder aktiv debuggen musst, kannst du in der Coolify Container Console (satis-builder) einen manuellen Build starten. Der README-Befehl ist:

/satis/bin/satis build -vvv /config/satis.json /build/output

Für eine schnelle Diagnose sind außerdem diese Checks hilfreich (ebenfalls aus der README):

env | grep SATIS

cat /config/satis.json

ls -lah /build/output/

Caveat: Wenn /config/satis.json nicht so aussieht, wie du es erwartest, liegt das Problem fast immer in den Environment-Variablen (z. B. falsches JSON, falsche Homepage, falsche Repo-URLs). Debugge zuerst die generierte Konfiguration, bevor du tiefer in Satis selbst einsteigst.

Sicherheit und Betrieb: realistische Stolpersteine

ACCESS_TOKEN ist nicht optional, wenn du privat bleiben willst

Die README ist hier sehr klar: Ohne ACCESS_TOKEN ist das Repository öffentlich. Behandle den Token wie ein Secret. Generiere ihn ausreichend lang und zufällig (die README nennt openssl rand -hex 32 als Idee) und rotiere ihn, wenn du vermutest, dass er geleakt ist.

GitHub Rate Limits und Stabilität

Auch bei öffentlichen Repos ist ein GITHUB_TOKEN empfehlenswert, weil Builds sonst in Rate Limits laufen können. Symptome sind sporadische Fehlschläge oder sehr lange Build-Zeiten. Wenn du viele Repositories oder viele Tags hast, wird das relevanter.

Atomic Builds und Downtime

Das Repo wirbt mit Atomic Builds ohne Downtime. Praktisch bedeutet das: Der neue Output wird so erzeugt, dass der Webserver weiterhin konsistent ausliefert, während im Hintergrund neu gebaut wird. Trotzdem gilt: Wenn du während eines Builds testest, kann es je nach Timing so wirken, als wären Versionen „halb da“. Verlasse dich im Zweifel auf den Build-Log und prüfe den Output-Ordner.

Monitoring und Troubleshooting-Prozess

Für den Betrieb ist ein einfacher Ablauf sinnvoll:

• Bei fehlenden Packages: zuerst SATIS_REPOSITORIES prüfen (Platzhalter, Tippfehler, JSON).
• Dann /config/satis.json ansehen, ob die erwarteten Repos drin sind.
• Dann manuellen Build mit -vvv ausführen und auf GitHub/Auth-Fehler achten.
• Wenn Version fehlt: Tag-Existenz und Push der Tags prüfen, dann Build abwarten oder triggern.

Fazit: Schnell zu einer privaten Composer-Quelle – mit klaren Grenzen

Mit satis-coolify bekommst du eine sehr pragmatische Lösung, um eine private Composer-Registry auf Coolify zu betreiben: Docker Compose als Deployment-Format, Konfiguration über Environment-Variablen, automatische Builds im festen Intervall und Token-basierte Authentifizierung. Die größten Erfolgsfaktoren sind saubere JSON-Konfiguration in SATIS_REPOSITORIES, ein gültiger GITHUB_TOKEN (insbesondere für private Repos) und ein konsequent gesetzter ACCESS_TOKEN, damit dein Repository wirklich privat bleibt.

Wenn du das Setup einmal stabil hast, ist der laufende Betrieb angenehm: neue Repos hinzufügen, redeployen, fertig. Und wenn etwas hakt, liefern die Debug-Kommandos im Builder-Container sehr schnell Klarheit.