Next.js auf dem eigenen Server hosten und bei git push veröffentlichen

Der kurze Weg, Next.js auf dem eigenen Server zu hosten: Installieren Sie ein Deployment-Panel wie Coolify und verbinden Sie Ihr GitHub-Repository. Danach baut jeder git push die App und schaltet die neue Version per HTTPS live. Laut der Next.js-Dokumentation funktionieren alle Funktionen, wenn Sie mit einem Node.js-Server oder einem Docker-Container veröffentlichen, Sie sind also an keine besondere Plattform gebunden.

Welche Funktionen laufen auf dem eigenen Server?

Die Tabelle in der offiziellen Dokumentation ist kurz: Ein Node.js-Server und Docker unterstützen jede Funktion, der statische Export ist eingeschränkt. Auf einem einzelnen Server bedeutet das in der Praxis:

• Server Components, API-Routen und gestreamte Antworten funktionieren mit next start.
• next/image braucht keine zusätzliche Einrichtung, die Bilder werden auf dem Server verarbeitet.
• Caching und Incremental Static Regeneration (ISR) funktionieren auf einem Server mit dauerhafter Festplatte von selbst. Betreiben Sie mehrere Kopien, müssen Sie den Cache zwischen ihnen teilen.
• Die offizielle Empfehlung lautet, einen Reverse-Proxy vorzuschalten, statt Next.js direkt freizugeben. Coolify bringt dafür Traefik mit, und Traefik holt auch das Zertifikat.

Wie leistungsstark sollte der Server sein?

Der Build bestimmt, wie viel Speicher Sie brauchen, nicht die laufende App. next build erreicht die Spitze, und die App braucht danach weit weniger. Auch Coolify selbst braucht Speicher. Das sind die Werte, die wir auf echten Servern gemessen haben:

Das kleine Projekt war die Next.js-Beispiel-App von Coolify. Das größere war eine KI-Chat-App, geschrieben mit Next.js 16 und rund 85 Paketen, und bei 2 GB ging ihr bei der TypeScript-Prüfung der Speicher aus. Der Server hatte 2 GB Swap, und die Zahlen zeigen den Höchststand. Die Festplattennutzung nach dem ersten Build lag bei 13 bis 18 GB. Das sind unsere eigenen Messungen, und Ihr Projekt wird anders sein. Schlägt ein Build wegen fehlenden Speichers fehl, vergrößern Sie zuerst und verkleinern später wieder, wenn möglich.

Schritt für Schritt

1. Das Repository verbinden

Melden Sie sich in Coolify an, öffnen Sie Ihr Projekt auf der Seite Projects und drücken Sie New resource. Wählen Sie für ein öffentliches Repository Public Git Repository, geben Sie die Adresse ein und drücken Sie Check repository.

2. Einen Schlüssel hinzufügen, wenn das Repository privat ist

Gehen Sie im linken Menü unter Keys & Tokens zu Private Keys und erstellen Sie mit Generate ED25519 einen Schlüssel. Fügen Sie den öffentlichen Schlüssel auf GitHub auf der Seite Settings des Repositorys unter Deploy keys hinzu. Wählen Sie dann mit New resource die Option Private Git Repository (with Deploy Key) und geben Sie [email protected]:user/project.git ein. Lassen Sie Build pack auf Railpack stehen, das Next.js erkennt, und der Port bleibt bei 3000. Coolify kennzeichnet Railpack als Beta, wählen Sie bei Problemen also Ihr eigenes Dockerfile.

3. Umgebungsvariablen eintragen

Wechseln Sie auf der Seite Environment Variables zu Developer view und fügen Sie den Inhalt Ihrer .env-Datei ein. Ein Detail ist hier wichtig: Variablen, deren Namen mit NEXT_PUBLIC_ beginnen, werden beim Build in den Code geschrieben. Wenn Sie eine ändern, drücken Sie Redeploy: Das Panel erkennt, dass sich eine Build-Einstellung geändert hat, und baut neu. Geben Sie dieses Präfix niemals einem Schlüssel, den der Browser nicht sehen soll.

4. Die Domain verbinden

Legen Sie bei Ihrem Domainanbieter einen A-Record an, der auf die IP-Adresse des Servers zeigt. Gehen Sie in Coolify auf die Seite Domains, drücken Sie Add domain, wählen Sie https als Protokoll, geben Sie Ihre Domain ein, speichern Sie und veröffentlichen Sie erneut. Das Zertifikat wird automatisch angefordert und verlängert. Die Ports 80 und 443 müssen offen sein.

5. Veröffentlichen

Drücken Sie Deploy. Die Seite Deployments zeigt das Build-Protokoll live. Ist der Build fertig, bedient der alte Container weiter, bis der neue bereit ist.

Wie wird aus git push eine Veröffentlichung?

Bei jedem Push sendet GitHub eine signierte Anfrage an das Panel. Das Panel prüft die Signatur und baut die App für diesen Branch neu, und eine Anfrage mit falscher Signatur wird abgewiesen. So richten Sie es ein:

1. Kopieren Sie auf der Seite Webhooks der App die Webhook URL aus dem GitHub-Abschnitt, tragen Sie bei Webhook secret einen zufälligen Wert mit mindestens 16 Zeichen ein und speichern Sie.
2. Öffnen Sie auf GitHub die Settings des Repositorys, gehen Sie zu Webhooks und drücken Sie Add webhook.
3. Tragen Sie die Adresse bei Payload URL und denselben Wert bei Secret ein. Setzen Sie Content type auf application/json und lassen Sie push als einziges Ereignis stehen.

Zum Ausprobieren:

git commit --allow-empty -m "deploy test"

git push

Der neue Build erscheint auf der Seite Deployments. Beim kleinen Beispielprojekt ging ein neuer Commit dank des Build-Caches in 41 Sekunden live. GitHub muss die Adresse des Panels erreichen können, und da das Panel mit einer öffentlichen HTTPS-Adresse installiert wird, ist nichts Zusätzliches nötig.

Häufige Fehler

Bei der Next.js-Option von Seturack kommt Coolify fertig installiert an: Der lokale Server ist validiert, der Willkommensassistent ist erledigt, und das Panel öffnet sich über HTTPS. Adresse und Passwort erscheinen in Ihrem Panel, und Sie beginnen damit, GitHub zu verbinden. Sie haben Root-Zugriff und können alles im Panel verwalten, wenn Sie das bevorzugen. Tägliche Sicherungen sind im Preis enthalten, und der Traffic ist unbegrenzt. Die Größe stellen Sie mit Reglern auf der Seite Next.js VPS ein.

Fertig eingerichtet bei Seturack: Next.js, Coolify.