thanatornPik/nextjs-skill-app-workshop

Docker Next.js Lokaler Bereitstellungs-Skill

Zweck

Verwende diesen Skill, um eine Next.js-Anwendung mit Docker zu erstellen und auszuführen, wobei ein versionierter Image-Tag verwendet wird.

Dieser Skill darf den Projektnamen nicht fest kodieren. Leite den Image-Namen aus dem aktuellen Repository ab, es sei denn, der Benutzer gibt einen spezifischen Namen an.

Projektnamensauflösung

Vor dem Erstellen bestimme diese Werte:

PROJECT_NAME=<aufgelöster Projektname>
IMAGE_NAME=<aufgelöster Image-Name>
IMAGE_VERSION=<aufgelöste Version>
IMAGE_TAG=${IMAGE_NAME}:${IMAGE_VERSION}
CONTAINER_NAME=<aufgelöster Container-Name>
ENV_FILE=<aufgelöste Umgebungsdatei>
HOST_PORT=<aufgelöster Host-Port>
CONTAINER_PORT=<aufgelöster Container-Port>

Auflösungsregeln:

1. Wenn der Benutzer einen Image-Namen angibt, verwende ihn.

2. Andernfalls lies package.json und verwende das Feld name.

3. Wenn package.json keinen name hat, verwende den aktuellen Ordnernamen.

4. Normalisiere den Image-Namen:

   • in Kleinbuchstaben
   • ersetze Leerzeichen und Unterstriche durch Bindestriche
   • entferne ungültige Docker-Image-Namenszeichen

5. Wenn der Benutzer eine Version angibt, verwende sie.

6. Andernfalls standardmäßig 1.0.0.

7. Wenn der Benutzer einen Container-Namen angibt, verwende ihn.

8. Andernfalls verwende den normalisierten Image-Namen als Container-Namen.

9. Wenn der Benutzer eine Umgebungsdatei angibt, verwende sie.

10. Andernfalls standardmäßig .env.production.

11. Wenn der Benutzer Ports angibt, verwende sie.

12. Andernfalls standardmäßig HOST_PORT=4000 und CONTAINER_PORT=3000.

Beispiel:

package.json name: nextjs-skill-app-workshop

PROJECT_NAME=nextjs-skill-app-workshop
IMAGE_NAME=nextjs-skill-app-workshop
IMAGE_VERSION=1.0.0
IMAGE_TAG=nextjs-skill-app-workshop:1.0.0
CONTAINER_NAME=nextjs-skill-app-workshop
ENV_FILE=.env.production
HOST_PORT=4000
CONTAINER_PORT=3000

Sicherheitsregeln

Vor dem Ausführen von Build- oder Run-Befehlen:

1. Bestätige, dass das aktuelle Arbeitsverzeichnis das Projektverzeichnis ist.

2. Bestätige, dass die Dockerfile existiert.

3. Bestätige, dass die Umgebungsdatei existiert.

4. Bestätige, dass Docker installiert und ausgeführt wird.

5. Überprüfe, ob der angeforderte Image-Tag bereits lokal existiert.

6. Überprüfe, ob der angeforderte Container-Name bereits existiert.

7. Gib niemals Geheimnisse aus der Umgebungsdatei aus.

8. Verwende den latest-Tag nur, wenn der Benutzer explizit danach fragt.

9. Führe keine zerstörerischen Bereinigungsbefehle aus wie:

   • docker system prune
   • docker image prune
   • docker volume prune

10. Stoppe, entferne oder ersetze keinen vorhandenen Container ohne explizite Bestätigung des Benutzers.

11. Baue keinen vorhandenen Versionstag ohne klare Bestätigung des Benutzers neu.

Vorflug-Checks

Führe diese Checks zuerst aus:

pwd
ls -la

test -f package.json && echo "OK: package.json gefunden" || echo "WARN: package.json nicht gefunden"
test -f Dockerfile && echo "OK: Dockerfile gefunden" || echo "FEHLER: Dockerfile nicht gefunden"
test -f "$ENV_FILE" && echo "OK: Umgebungsdatei gefunden: $ENV_FILE" || echo "FEHLER: Umgebungsdatei nicht gefunden: $ENV_FILE"

docker --version
docker info >/dev/null && echo "OK: Docker-Daemon läuft" || echo "FEHLER: Docker-Daemon läuft nicht"

Wenn die Dockerfile fehlt, brich ab und melde das Problem.

Wenn die Umgebungsdatei fehlt, brich ab und melde das Problem. Erstelle keine Platzhalter-Umgebungsdatei, es sei denn, der Benutzer bittet darum.

Wenn der Docker-Daemon nicht läuft, brich ab und sage dem Benutzer, Docker Desktop oder Docker Engine zu starten.

Vorgeschlagene Hilfsbefehle

Um den Image-Namen aus der package.json abzuleiten:

node -p "require('./package.json').name"

Wenn package.json nicht existiert oder keinen name hat, verwende den aktuellen Verzeichnisnamen:

basename "$PWD"

Um einen Projektnamen manuell zu normalisieren, verwende Kleinbuchstaben und Kebab-Schreibweise.

Beispiel:

My Next App -> my-next-app
nextjs_skill_app -> nextjs-skill-app

Versions-Tag-Überprüfung

Überprüfe vor dem Erstellen, ob der angeforderte Image-Tag bereits existiert:

docker image inspect "$IMAGE_TAG" >/dev/null 2>&1 \
  && echo "EXISTIERT: $IMAGE_TAG" \
  || echo "VERFÜGBAR: $IMAGE_TAG"

Liste auch vorhandene lokale Versionen für dieses Image auf:

docker images "$IMAGE_NAME" --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedSince}}\t{{.Size}}"

Wenn der angeforderte Image-Tag bereits existiert:

1. Führe kein docker build aus.
2. Melde, dass die Version bereits lokal existiert.
3. Schlage die nächste Patch-Version vor, z. B. 1.0.1.
4. Frage den Benutzer, ob er eine neue Version verwenden oder denselben Tag explizit neu erstellen möchte.

Baue einen vorhandenen Tag nur neu, wenn der Benutzer eindeutig zustimmt.

Container-Name-Überprüfung

Überprüfe vor dem Starten des Containers, ob der Container-Name bereits existiert:

docker ps -a --filter "name=^/${CONTAINER_NAME}$" \
  --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

Wenn ein Container mit demselben Namen bereits existiert:

1. Starte keinen weiteren Container mit demselben Namen.
2. Melde den Status des vorhandenen Containers.
3. Frage den Benutzer, ob er ihn stoppen/entfernen oder einen anderen Container-Namen verwenden möchte.
4. Entferne ihn nicht automatisch.

Build-Befehl

Wenn der Image-Tag nicht existiert, führe aus:

docker build -t "$IMAGE_TAG" .

Überprüfe nach dem Erstellen, ob das Image existiert:

docker image inspect "$IMAGE_TAG" >/dev/null \
  && echo "OK: Image erfolgreich erstellt: $IMAGE_TAG" \
  || echo "FEHLER: Image nach Erstellung nicht gefunden: $IMAGE_TAG"

Run-Befehl

Wenn das Image existiert und der Container-Name verfügbar ist, führe aus:

docker run --restart=always -d \
  --name "$CONTAINER_NAME" \
  --env-file "$ENV_FILE" \
  -p "${HOST_PORT}:${CONTAINER_PORT}" \
  "$IMAGE_TAG"

Validierung nach dem Start

Nach dem Starten des Containers validiere mit:

docker ps --filter "name=^/${CONTAINER_NAME}$" \
  --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

docker logs --tail=80 "$CONTAINER_NAME"

curl -I "http://localhost:${HOST_PORT}"

Erwartetes Ergebnis:

1. Container-Status sollte Up sein.
2. Port-Zuordnung sollte ${HOST_PORT}->${CONTAINER_PORT} enthalten.
3. Logs sollten keine fatalen Fehler anzeigen.
4. curl -I sollte eine HTTP-Antwort wie 200, 301, 302, 307 oder 308 zurückgeben.

Wenn curl fehlschlägt, überprüfe die Logs und melde die wahrscheinliche Ursache.

Behandlung häufiger Fehler

Image-Tag existiert bereits

Melde:

Image-Tag existiert bereits lokal:
<IMAGE_TAG>

Empfohlene Aktion:
- Verwende eine neue Patch-Version, z. B. 1.0.1
- Oder bestätige explizit, denselben Tag neu zu erstellen

Container-Name existiert bereits

Melde:

Container existiert bereits:
<CONTAINER_NAME>

Bitte bestätige, ob er gestoppt/entfernt werden soll, oder gib einen anderen Container-Namen an.

Port bereits belegt

Überprüfe:

lsof -i :"$HOST_PORT"

Melde den Prozess, der den Port verwendet, und frage, ob der Benutzer HOST_PORT ändern möchte.

Umgebungsdatei fehlt

Melde:

Umgebungsdatei wurde nicht gefunden:
<ENV_FILE>

Ich kann den Container nicht mit --env-file starten, bis diese Datei existiert.

Drucke oder leite keine Geheimnisse ab.

Docker-Daemon läuft nicht

Melde:

Docker ist installiert, aber der Daemon läuft nicht.
Starte Docker Desktop oder Docker Engine und führe die Vorflug-Checks erneut aus.

Endgültiges Antwortformat

Wenn abgeschlossen, melde:

Ergebnis:
- Projekt: <PROJECT_NAME>
- Image: <IMAGE_TAG>
- Container: <CONTAINER_NAME>
- Umgebungsdatei: <ENV_FILE>
- Port: http://localhost:<HOST_PORT>
- Neustart-Richtlinie: always
- Validierung: bestanden/fehlgeschlagen

Verwendete Befehle:
<liste wichtiger Befehle>

Hinweise:
<etwaige Warnungen, bestehende Image-/Container-Konflikte oder Folgeaktionen>

Wenn der Workflow aufgrund eines vorhandenen Versionstags, einer fehlenden Umgebungsdatei, eines vorhandenen Containers, eines Docker-Fehlers oder eines Port-Konflikts stoppt, gib das blockierende Problem und den sichersten nächsten Befehl klar an.