Deployment einer PayloadCMS App auf Coolify

PayloadCMS ist ein leistungsstarkes, flexibles Headless-CMS, das auf Node.js basiert und ideal für maßgeschneiderte Projekte geeignet ist. Als Beispiel: Diese Website verwendet selbst PayloadCMS als Backend, um Inhalte dynamisch und effizient zu verwalten.

Coolify, eine Plattform für das Deployment von Webanwendungen & diversen anderen Services, nimmt dir die gesamte Infrastrukturverwaltung ab. In diesem Beitrag werde ich dir Schritt für Schritt zeigen, wie ich meine Payload Apps auf Coolify hoste. Ich werde detailliert auf alle notwendigen Schritte eingehen, von der Vorbereitung der App über die Einrichtung der benötigten Dienste bis hin zum finalen Deployment.

Die Kombination aus PayloadCMS und Coolify bietet dir die perfekte Grundlage, um robuste, skalierbare Anwendungen zu entwickeln und zu betreiben, ohne dich mit komplizierter Infrastruktur auseinandersetzen zu müssen.

Voraussetzungen

Stelle sicher, dass du folgende Punkte erfüllst:

• Coolify 4-Installation: Du benötigst einen bereits laufenden Server, auf dem Coolify 4 installiert ist. Ein Beispiel hierfür könnte ein Server von Hetzner sein. Falls du Coolify 4 noch nicht eingerichtet hast, kannst du den offiziellen Setup-Guide von Coolify nutzen, um die Installation durchzuführen.
• Grundlegende Kenntnisse in Node.js: Da PayloadCMS auf Node.js basiert, solltest du mit den Grundlagen von Node.js und dem Package Manager deiner Wahl (ich empfehle dir pnpm) vertraut sein.
• GitHub-Repo: Deine Payload App solltest du in einem GitHub Repository hosten sein, da Coolify dieses für das Deployment verwenden wird.
• Domain und SSL: Optional, aber empfehlenswert, ist die Verfügbarkeit einer eigenen Domain und die Einrichtung von SSL-Zertifikaten für deine Anwendung.

Sobald diese Voraussetzungen erfüllt sind, kannst du mit der Vorbereitung deiner App und dem Deployment auf Coolify beginnen.

Vor dem Deployment auf Coolify

Bevor du mit dem Deployment auf Coolify beginnst, musst du sicherstellen, dass du eine vollständig funktionsfähige PayloadCMS-App hast. Dieser Beitrag konzentriert sich darauf, wie du diese App auf Coolify deployen kannst. Falls du noch keine PayloadCMS-App erstellt hast, empfehle ich dir, zunächst die offizielle Dokumentation von PayloadCMS zu konsultieren und eine App aufzusetzen.

Deine App sollte lokal einwandfrei builden, und der Production Build sollte ohne Fehler starten. Es ist essenziell, dass du alle potenziellen Probleme bereits lokal behebst, da dies den Deployment-Prozess erheblich vereinfacht und spätere Komplikationen auf dem Server vermeidet.

Sobald deine App lokal reibungslos läuft und auf einem Github Repo gehostet ist, kannst du mit den nächsten Schritten fortfahren und das Deployment auf Coolify vorbereiten.

Einrichten in Coolify

Das Einrichten in Coolify ist eigentlich relativ simpel. Hier ist der Ablauf, wie ich ihn durchführe:

Projekt in Coolify

Öffne deine Coolify-Instanz im Browser und navigiere zu "Projects" – falls noch keines vorhanden ist, erstelle eines.

Klicke auf die "production"-Schaltfläche und dann auf "+ Add Resource". Unter "Applications" wähle deine bevorzugte Variante. Da ich die hier verwendete Coolify-Instanz via GitHub Apps verbunden habe, werde ich auch diese Variante wählen. (Das Verbinden via GitHub Apps ist unter dem Menüpunkt "Sources" möglich).

Wähle die GitHub App, suche das gewünschte GitHub-Repo aus der Dropdownliste und klicke auf "Load repository". Triff danach die entsprechenden Einstellungen und klicke dann auf "Continue".

App Konfiguration

Hier konfigurierst du nun die Payload-App. Du kannst einen erkennbaren Namen vergeben, eine Beschreibung hinzufügen und eine eigene URL angeben. Das wichtigste hier ist jedoch der Punkt Build.

1. Commands: Je nachdem, welche Build/Start-Skripte in deiner package.json definiert sind, musst du diese hier korrekt eingeben.
2. Base Directory: Dies ist individuell. Da ich hier ein Monorepo verwende und sich die Payload-App in einem Unterverzeichnis befindet, gebe ich hier den entsprechenden Pfad an.
3. Publish Directory: Dies sollte das Verzeichnis mit deinem Production Build sein, in meinem Fall /dist.

Hier zur Veranschaulichung:

Datenbank

Ohne Datenbank keine Payload-App – deshalb werden wir direkt in Coolify eine DB erstellen und via Connection String mit der App verbinden. Wir navigieren wieder zurück zu Projects -> Dein Projekt -> production (oder das Environment, in dem sich die Payload App befindet).

Ein Klick auf "+ New" bei Resources, bevorzugte DB (PostgreSQL oder MongoDB) auswählen und "Start" klicken. Easy as that!

Unter dem Punkt Network kopiere dir den Connection String (Postgres URL), du wirst ihn gleich als ENV-Variable bei der Payload-App hinterlegen.

Env Variablen setzen

Navigiere zurück zur Konfiguration deiner Payload App. In der Sidebar, klicke auf Environment Variables und füge alle benötigten Variablen ein die deine Payload App benötigt.

Wichtig hierbei: Das Kästchen bei "Build Variable?" sollte angehakt sein. Wenn du den Developer View verwendet hast, um deine ENV-Variablen zu pflegen, musst du wieder in den Normal View wechseln und das Kästchen anhaken!

Persistent Media uploads

Wenn du bisher alle Schritte verfolgt hast, bist du grundsätzlich bereit, die App zu deployen. Hier ist jedoch noch ein kleiner Tipp, falls du Media-Uploads in deiner Payload App verwendest.

Um zu verhindern, dass deine Uploads zwischen den Deployments verloren gehen, navigiere zu Storages, direkt unter dem Punkt Environment Variables.

Klicke auf "+ Add", unter Volume Mount gib einen Namen und einen Destination Path ein. In meinem Fall befindet sich das Upload-Verzeichnis (/media) im Root der Payload-App. Achtung: /app/ ist der Root des Docker-Containers, in dem die App läuft.

Die App auf Coolify deployen

Nun können wir (versuchen) die Payload App zu deployen. Hierzu klickst du lediglich auf "Deploy". Du wirst automatisch zu Deployment Seite geleitet und kannst dir den ganzen Prozess ansehen. Um mehr Infos zum Deployment zu sehen empfehle ich auf "Show Debug Logs" zu klicken.

Sollte während des Deployments ein Fehler auftreten, kannst du so die Ursache ausfindig machen und beheben.

Fazit

Mit dieser Anleitung hast du nun die wichtigsten Schritte kennengelernt, um eine PayloadCMS App erfolgreich auf Coolify zu deployen. Die Kombination dieser beiden leistungsstarken Tools ermöglicht es dir, komplexe Webanwendungen mit minimalem Aufwand zu verwalten und zu skalieren. Coolify nimmt dir die Last der Infrastrukturverwaltung ab, während PayloadCMS dir maximale Flexibilität beim Erstellen und Verwalten von Inhalten bietet.

Wenn du diesen Prozess einmal eingerichtet hast, kannst du zukünftige Deployments deiner App schnell und einfach durchführen. Damit ist deine Anwendung nicht nur schnell online, sondern auch sicher und zuverlässig gehostet.

Ich hoffe, dass dir dieser Beitrag weitergeholfen hat und du jetzt besser verstehst, wie du deine PayloadCMS App auf Coolify bereitstellen kannst.

Viel Erfolg beim Deployment und beim Entwickeln deiner Projekte!