Eine QuickStart-Anleitung für das Hosting von Next.js auf Upsun

next.jsGitHubKonfiguration

13 Dezember 2023

Florent Huck

DevRel Ingenieur

Teilen Sie

Dieser Beitrag ist auch auf Französische und Englische.

Willkommen zu unserer QuickStart-Anleitung für das Hosting von Next.js (zum Zeitpunkt der Erstellung dieses Artikels ist die aktuellste Version von Next.js 14.0.3) auf Upsun. Wir zeigen Ihnen, wie einfach es ist, Next.js-Projekte auf unserem PaaS zu hosten. Folgen Sie einfach den unten aufgeführten Schritten und Sie werden alles in kürzester Zeit eingerichtet haben.

Kennen Sie schon das Upsun Demo-Tutorial, das Benutzern über die Konsole zur Verfügung steht? Es ist der perfekte Startpunkt, um herauszufinden, wie Upsun funktioniert und um ein besseres Verständnis für unser Angebot zu erlangen. Wenn Sie nach einer alternativen Methode suchen, um eine Anwendung auf Upsun bereitzustellen, z. B. mit der Upsun CLI, finden Sie nützliche Informationen in unserem speziellen Next.js-Leitfaden.

Bevor wir beginnen, gehen wir in diesem Tutorial davon aus, dass Sie die Upsun CLI bereits lokal installiert haben. Die folgenden Schritte basieren darauf:

Lokal beginnen

Wenn Sie bereits ein bestehendes Next.js GitHub Repository mit mindestens einer Hello world route haben, klonen Sie es bitte lokal mit dem folgenden Befehl und springen Sie dann zum zweiten Schritt: Konfigurieren Sie Ihr Projekt.

$ git clone git@github.com:<IhreRepoUrl>.git

Wenn Sie noch kein Next.js-GitHub-Repository haben, sind Sie hier genau richtig, die folgenden Schritte zeigen Ihnen, wie Sie eines einrichten und lokal klonen können.

1. Initialisieren Sie Ihr lokales Projekt

Das Wichtigste zuerst: Wenn Sie noch kein lokales Next.js-Projekt haben, müssen Sie ein neues Projekt lokal erstellen, indem Sie der Next.js-Installationsanleitung folgen. Bitte lesen Sie alle Schritte der Installationsanleitung, um alle Details zu erfahren. Zusammengefasst sind dies die drei Befehle, die benötigt werden, um eine lokale Next.js Anwendung zu erstellen:

$ mkdir my-nextjs-app
$ cd my-nextjs-app
$ npm install next@latest react@latest react-dom@latest

2. Initieren Sie Ihr Git-Repository

Sobald Sie ein neues Next.js-Projekt lokal erstellt haben, ist es an der Zeit, das lokale Git-Repository zu initialisieren und die lokalen Dateien mit dem folgenden Befehl zu übertragen:

$ git init
$ git add package.json package-lock.json
$ git commit -m "Init Next.js application"

Hinweis: Sie können das Hinzufügen der Ordner node_modules und .next zum Git-Repository ignorieren, da die Node-Module während des Build-Hooks später in diesem Prozess installiert werden. Verwenden Sie dazu die folgenden Befehle:


$ echo " node_modules"="">> .gitignore
$ echo "/.next" >> .gitignore
$ git add .gitignore && git commit -m "adding node_modules and .next folders in .gitignore file"

3. Hinzufügen einer Hello World Route

Um sicherzustellen, dass Ihre Next.js-Anwendung leicht zu testen ist, müssen Sie Ihre erste Next.js-Seite erstellen. Dazu erstellen Sie eine neue pages/index.tsx Datei, die ein einfaches Hello World Skript enthält, wie unten zu sehen:

export default function Page() {
 return <h1>Hello world, Next.js!</h1>
}

Übertragen Sie dann Ihre Datei mit den folgenden Befehlen:

$ git add pages/index.tsx
$ git commit -m "adding a Hello World"

4. Erstellen Sie Ihr GitHub-Repository

Der nächste Schritt besteht darin, ein GitHub-Repository zu erstellen. Folgen Sie dazu der offiziellen GitHub-Anleitung, die alle erforderlichen Informationen enthält.

5. Übertragen Sie den Quellcode in Ihr entferntes Repository

Der letzte Schritt der lokalen Einrichtung besteht darin, Ihren Quellcode mit folgendem Befehl in Ihr entferntes GitHub-Repository zu übertragen:

$ git remote add origin git@github.com:OWNER/REPOSITORY.git
$ git push -u origin main

Konfigurieren Sie Ihr Projekt

Um Ihre Next.js-Anwendung auf Upsun hosten zu können, benötigen Sieeinige YAML-Konfigurationsdateien im Stammverzeichnis Ihres Projekts, um das Verhalten Ihrer Anwendung zu steuern. Der folgende Code zeigt Ihnen, wie Sie diese Dateien automatisch vorgenerieren können.

Diese YAML-Konfigurationsdateien befinden sich in einem .upsun/-Ordner in der Wurzel Ihres Quellcodes, dessen Architektur folgendermaßen aussehen wird:

my-nextjs-app
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>

Bitte beachten Sie: Eine zusätzliche .environment-Datei kann sich auch im Stammverzeichnis Ihres Quellcodes befinden, diese Datei kann Upsun-spezifische Umgebungsvariablen enthalten.

Um diese YAML-Dateien vorab zu generieren, verwenden Sie bitte den folgenden Befehl upsun project:init aus der Wurzel Ihres Next.js-Projekts und folgen Sie den Aufforderungen, wie Sie unten sehen können:

$ upsun project:init
Welcome to Upsun!
Let's get started with a few questions.

We need to know a bit more about your project. This will only take a minute!

✓ Detected stack: Next.js
✓ Detected runtime: JavaScript/Node.js
✓ Detected dependency managers: Npm
Tell us your project’s application name: [app]

                                                (_/)
We're almost done...  =(^.^)=
Last but not least, unless you're creating a static website, your project uses services. Let's define them:

Select all the services you are using: []

You have not selected any service, would you like to proceed anyway? [Yes]

┌───────────────────────────────────────────────────┐
│   CONGRATULATIONS!                                                                                               │
│                                                                                                                                    │
│   We have created the following files for your:                                                          │
│     - .upsun/config.yaml                                                                                              │
│                                                                                                                                    │
│   We're jumping for joy! ⍢                                                                                         │
└───────────────────────────────────────────────────┘
        │ /
        │/
        │
  ( /)
  ( . .)
  o (_(")(")
  
You can now deploy your application to Upsun!
To do so, commit your files and deploy your application using the Upsun CLI:
  $ git add .
  $ git commit -m 'Add Upsun configuration files' 
  $ upsun project:set-remote
  $ upsun push

Der Befehl upsun project:init (Abkürzung upsun ify) erkennt automatisch, dass Sie einen Next.js-Stack verwenden, fragt, ob Sie Dienste hinzufügen möchten (bitte fügen Sie vorerst keine hinzu) und generiert die entsprechenden .upsun/config.yaml YAML-Dateien, etwa so:

# Vollständige Liste aller verfügbaren Eigenschaften: https://docs.upsun.com/create-apps/app-reference.html
applications:
 app:
   source:
     root: "/"
   type: "nodejs:20"
   mounts:
     "/.npm":
       source: "storage"
       source_path: "npm"
   web:
     commands:
       start: "npx next start -p $PORT"
     upstream:
       socket_family: tcp
    locations:
      "/":
        passthru: true
   build:
     flavor: none
   dependencies:
     nodejs:
       sharp: "*"
   hooks:
     build: |
       set -eux
       npm i
       npm exec next build
routes:
 "https://{default}/":
   type: upstream
   upstream: "app:http"
 "https://www.{default}/":
   type: redirect
   to: "https://{default}/"

Übertragen Sie dann Ihre neuen Dateien mit dem folgenden Befehl, und die Projektkonfiguration ist abgeschlossen:

$ git add .upsun/config.yaml
$ git commit -m "Upsun config files"
$ git push

Erstellen Sie ein neues Upsun-Projekt

Bitte beachten Sie: Wenn Sie noch kein Upsun-Konto haben, erstellen Sie bitte eines, um die folgenden Schritte durchzuführen.

Der nächste Schritt bei der Einrichtung von Next.js auf Upsun besteht darin, ein Projekt zu erstellen, was über die Konsole einfach zu bewerkstelligen ist. Klicken Sie auf der Startseite Ihrer Konsole (alle Projekte) in der oberen rechten Ecke auf die Schaltfläche " Projekt erstellen", wie unten dargestellt:

Wenn Sie noch keine Organisation für das Projekt erstellt haben, werden Sie zunächst aufgefordert, eine solche zu erstellen. Sobald Sie dies getan haben, wählen Sie diese Organisation aus dem Dropdown-Menü aus und wählen Sie dann " Mit GitHub bereitstellen", wie auf dem Bildschirm unten zu sehen:

Wählen Sie dann die Option Mit GitHub verbinden aus, wie hier zu sehen ist:

Wählen Sie im nächsten Formular, das auf dem Bildschirm unten zu sehen ist, Ihre GitHub-Organisation aus der ersten Dropdown-Liste aus, wählen Sie dann Installieren & Autorisieren und geben Sie die GitHub-Anmeldedaten ein. Wählen Sie Ihre GitHub-Organisation und das zuvor erstellte GitHub-Repository aus und klicken Sie auf Weiter.

Sie werden dann zu Schritt drei der Einrichtung weitergeleitet, wie unten zu sehen, wo Sie verschiedene Details wie Projektname, Umgebungsname und Region eingeben müssen . Wählen Sie anschließend Projekt erstellen.

Auf der nächsten Seite sehen Sie auf der linken Seite weitere Einrichtungsanweisungen, falls Sie diese benötigen, während der Prozess der Projekterstellung im Hintergrund weiterläuft. Auf der rechten Seite können Sie den Prozess der Projekterstellung verfolgen und werden informiert, wenn er abgeschlossen ist, wie auf dem Bildschirm unten zu sehen:

Sobald Ihr Projekt erstellt wurde, wird der GitHub-Integrationsprozess Ihre Anwendung automatisch auf der Grundlage des Quellcodes Ihres GitHub-Repositorys bereitstellen. Warten Sie, bis die Integration die Bereitstellung abgeschlossen hat. Anschließend werden die Informationen zu Ihrer Anwendung angezeigt, die Sie in der folgenden Abbildung sehen können:

Zeit für die Bereitstellung, richtig?

Und einfach so ist es Zeit für die Bereitstellung! Aber warten Sie...

Da Sie bereits sichergestellt haben, dass Ihr GitHub-Quellcode Upsun-ready ist, wurde Ihr Projekt während der Projekterstellung automatisch bereitgestellt und Ihre Anwendung ist live, eine Bereitstellung ist nicht erforderlich und das erste Backup Ihrer Anwendung wird automatisch durchgeführt. Überprüfen Sie Ihre neue Projekt-URL, die Sie am unteren Rand der Konsolenoberfläche finden können.

Der nächste Schritt besteht darin, auf Ihre Projektkonsole zuzugreifen, indem Sie unten auf der Einrichtungsseite auf die Schaltfläche Projekt anzeigen klicken. Und schon ist Ihre Next.js-Anwendung live und Sie können mit ihr spielen und viele neue Funktionen hinzufügen!

Wie sieht es mit Updates aus?

1. Zuweisung von Ressourcen

Während des ersten Pushs Ihrer Produktionsumgebung verwendet Upsun die Standardgröße für jeden Ihrer Service/App-Container. Die Standardeinstellung ist auf 0,5 CPU und 0,2 GB RAM gesetzt, aber das ist mehr als für diesen Container benötigt wird, also lassen Sie uns das auf einen angemesseneren Wert reduzieren.

Wenn Sie benutzerdefinierte Ressourcen (CPU, Arbeitsspeicher und Festplatte) für die verschiedenen Containerdefinieren müssen , ist das Verfahren einfach. Klicken Sie in der Umgebungsansicht auf den Link Ressourcen konfigurieren im Benachrichtigungsblock am oberen Rand. Dies kann auch über die CLI erfolgen.

Im Allgemeinen sollten die folgenden Ressourcen effektiv sein, aber Sie können diese Werte gerne an die Bedürfnisse Ihrer Anwendung anpassen:

CPU: 0.1, Speicher 64 MB
1 Instanz
1024 MB Festplatte/Speicherplatz

Nachdem Sie Ihre Auswahl bestätigt haben, übernimmt Upsun Ihre Auswahl, sammelt die zuvor erstellten Images, wendet Ihre Ressourcenauswahl auf diese an und stellt Ihre vollständige Anwendung erneut bereit. Wenn Sie weitere Informationen benötigen, lesen Sie bitte unsere Dokumentation über die Verwaltung von Ressourcen auf Upsun.

2. Code-Änderungen

Bitte beachten Sie: Die gleichen Regeln, die für Git-Workflows gelten, gelten auch für Upsun-Projekte: Aktualisieren Sie niemals direkt Ihre Produktionsumgebung, und erstellen Sie immer einen neuen Branch, um Ihre lokalen Änderungen zu testen.

Um Ihre Anwendung zu aktualisieren, erstellen Sie wie gewohnt einen neuen Git-Branch über Ihr Terminal, implementieren Sie die gewünschten Änderungen und pushen Sie den Branch in Ihr GitHub-Repository.

$ git switch -c update-hello 
// Nehmen Sie einige Codeänderungen vor, z. B. die Änderung der Hello world-Nachricht
$ git add . && git commit -m “Change Hello world”
$ git push -u origin update-hello

Bitte beachten Sie: Wenn Sie die Upsun CLI bereits installiert haben, können Sie auch den Befehl upsun push (anstelle von git push) verwenden, da er die upsun Git-Remote verwendet, um Ihren Code zu pushen, und diese Remote ist als dieselbe wie origin definiert.

Es wird automatisch eine neue, inaktive Upsun-Vorschauumgebung erstellt , die auf dem Quellcode Ihres Branches und den Daten der übergeordneten Umgebung (Datenbank und/oder Assets) basiert. Diese neue Umgebung ist standardmäßig nicht aktiv , was bedeutet, dass sie keine Ressourcen verbraucht. Sie müssen sie also aktivieren, wenn Sie das erste Mal einen neuen Branch in Ihr Repository einfügen, indem Sie den folgenden Befehl verwenden:

$ upsun environment:activate
Are you sure you want to activate the environment update-hello (type: development)? [Y/n] y
Activating environment update-hello
…

Bitte beachten Sie: Da wir noch keine Ressourcen für unseren Anwendungscontainer konfiguriert haben, wird der Aktivierungsprozess fehlschlagen, aber keine Sorge, das ist zu erwarten. Das Problem wird mit der für Januar 2024 erwarteten Veröffentlichung von Git25 behoben, da diese neue Git-Version die Einstellungen der übergeordneten Ressourcen erfasst und verwendet, wie sie sind. In der Zwischenzeit folgen Sie bitte den oben genannten Schritten, um die Ressourcen in Ihrer Vorschauumgebung zu konfigurieren.

Am Ende dieser Aktivierung ist Ihre Vorschauumgebung bereitgestellt und Sie können entweder über die Konsole darauf zugreifen, indem Sie zur entsprechenden Umgebung gehen und auf ihre vordere URL klicken, oder indem Sie den folgenden CLI-Befehl verwenden:

$ upsun environment:url -primary

Und schon sind Sie bereit, Ihre Next.js-Anwendungen auf Upsun zu hosten. Halten Sie die Augen offen für viele weitere Anleitungen, die in Kürze erscheinen werden. In unserem Blog werden jede Woche neue Artikel zu verschiedenen Themen veröffentlicht. Erfahren Sie mehr über die Funktionen und Möglichkeiten von Upsun.