Zum Inhalt springen

Deployments ohne Ausfall für Node-Apps mit Docker Compose · Teil 4 von 11 der Serie

Teil 4: Eine Pipeline, die testet und baut

Lass GitHub oder GitLab nach jedem Push die Arbeit machen: die Tests ausführen, das Image bauen und es unter zwei Namen in ein Regal stellen, in dem der Server es findet.

Quest-Ziele

  • Verstehen, was eine Pipeline und eine Registry sind
  • Eine Pipeline schreiben, die die Tests ausführt und dann das Image baut
  • Jedes Image unter seiner Commit-ID und als „production“ ablegen
  • Die Pipeline-Läufe und die Images auf deiner Plattform finden
  • Sehen, wie ein fehlschlagender Test eine kaputte Version stoppt, bevor sie gebaut wird

Du kannst das Image jetzt auf deinem eigenen Rechner bauen. Aber ein Deployment, das von deinem Rechner abhängt, hängt von dir ab: davon, dass du an die Tests denkst, dass du vom richtigen Commit baust, dass nichts Halbfertiges herumliegt. Ab diesem Teil macht das eine Maschine, jedes Mal auf dieselbe Weise.

Pipeline und Registry

Eine Pipeline ist eine Liste von Schritten, die GitHub oder GitLab nach jedem Push auf ihren eigenen Maschinen ausführen. Du beschreibst die Schritte in einer Datei in deinem Repository. Die Plattform startet eine frische Maschine, holt deinen Code, arbeitet die Liste ab und zeigt dir, was passiert ist. Schlägt ein Schritt fehl, hält die Pipeline dort an und wird rot.

Eine Registry ist ein Regal für Images. Die Pipeline stellt jedes Image, das sie baut, dort ab, und der Server holt es später von dort. Beide Plattformen haben eine Registry eingebaut, einzurichten gibt es also nichts.

Jedes Image kommt unter zwei Namen ins Regal. Docker nennt so einen Namen Tag:

  • Die Commit-ID. Dieser Name bewegt sich nie. Was auch später passiert, das Image jedes Commits findest du wieder.

  • production. Dieser Name wandert mit jedem Build weiter und zeigt immer auf das neueste Image. Er bedeutet „das soll auf dem Server laufen“, und der Server folgt diesem Namen und sonst nichts.

Die Pipeline-Datei

Die Datei sieht auf den beiden Plattformen verschieden aus, sagt aber dasselbe: Führ die Tests aus, und nur wenn sie bestehen, bau das Image und leg es unter beiden Namen ab.

Ich arbeite mit

GitHub

Auf GitHub heißt eine Pipeline Workflow, und Workflows liegen im Ordner .github/workflows. Leg .github/workflows/deploy.yml an:

.github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches:
      - main

permissions:
  contents: read
  packages: write

env:
  IMAGE: ghcr.io/your-name/guestbook

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 26
          cache: npm
      - run: npm ci
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Log in to the registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${{ github.actor }} --password-stdin
      - name: Build the image
        run: docker build --build-arg APP_VERSION="$GITHUB_SHA" --tag "$IMAGE:$GITHUB_SHA" .
      - name: Push it, under its commit and as "production"
        run: |
          docker push "$IMAGE:$GITHUB_SHA"
          docker tag "$IMAGE:$GITHUB_SHA" "$IMAGE:production"
          docker push "$IMAGE:production"

Ändere your-name in der Zeile IMAGE in deinen GitHub-Namen, in Kleinbuchstaben, auch wenn dein Name Großbuchstaben hat: Docker nimmt Image-Namen nur kleingeschrieben an. Von oben:

  • on sagt, wann der Workflow läuft: bei jedem Push auf den Branch main.

  • permissions sagt, was der Workflow darf. GitHub gibt jedem Lauf einen eigenen Schlüssel, den GITHUB_TOKEN. Hier darf er den Code lesen und Pakete schreiben, dort landen die Images. Alles, was nicht aufgeführt ist, ist verboten.

  • jobs sind die zwei Aufgaben. Jeder Job bekommt eine frische Maschine (runs-on) und arbeitet seine steps ab.

  • Der Job test holt deinen Code (checkout), installiert Node.js 26 (setup-node, das auch npms Downloads für den nächsten Lauf aufhebt), installiert die Abhängigkeiten mit npm ci und führt npm test aus, den Befehl, den du aus Teil 1 kennst.

  • Der Job build hat needs: test: Er startet erst, wenn die Tests bestanden sind. Er meldet sich mit dem Schlüssel des Laufs bei GitHubs Registry an, ghcr.io, baut das Image und legt es unter beiden Namen ab. Docker ist auf GitHubs Maschinen schon installiert.

  • $GITHUB_SHA ist die ID des Commits, zu dem der Lauf gehört. Sie wird der erste Name des Images und, als APP_VERSION, die Version in der Fußzeile des Gästebuchs. Das ist der Build vom Ende von Teil 3, von einer Maschine erledigt.

GitLab

Auf GitLab ist die Pipeline eine einzige Datei im obersten Ordner des Repositorys. Leg .gitlab-ci.yml an, mit dem Punkt am Anfang:

.gitlab-ci.yml
stages:
  - test
  - build

test:
  stage: test
  image: node:26-alpine
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: docker:29-cli
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: '/certs'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY --username $CI_REGISTRY_USER --password-stdin
    - docker build --build-arg APP_VERSION=$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA $CI_REGISTRY_IMAGE:production
    - docker push $CI_REGISTRY_IMAGE:production

Zu ändern gibt es darin nichts. Von oben:

  • stages sind die zwei Schritte, in ihrer Reihenfolge. Schlägt ein Job in test fehl, startet build nicht.

  • Jeder Job läuft in einem Container, und image sagt, in welchem. Der Job test läuft in einem mit Node.js 26, installiert die Abhängigkeiten mit npm ci und führt npm test aus, den Befehl, den du aus Teil 1 kennst.

  • Der Job build hat eine Regel: Es gibt ihn nur in Pipelines für den Standard-Branch, also main. Tests laufen für jeden Branch, Images werden nur von main gebaut.

  • Um ein Image zu bauen, braucht der Job Docker. Sein eigener Container bringt den Befehl docker mit, und die Zeile unter services startet einen zweiten Container daneben, der das eigentliche Bauen übernimmt. DOCKER_TLS_CERTDIR lässt die beiden über eine verschlüsselte Verbindung miteinander reden.

  • Die Namen, die mit $CI_ anfangen, füllt GitLab für dein Projekt aus: die Adresse der Registry, ein Benutzer und ein Passwort, die nur gelten, solange der Job läuft, der Name des Images und die Commit-ID. Davon stellst du nichts selbst ein.

  • $CI_COMMIT_SHA ist die ID des Commits, zu dem die Pipeline gehört. Sie wird der erste Name des Images und, als APP_VERSION, die Version in der Fußzeile des Gästebuchs. Das ist der Build vom Ende von Teil 3, von einer Maschine erledigt.

Schau ihr zu

Die Pipeline startet mit dem Push, der ihre Datei auf die Plattform bringt:

~/projects/guestbook
$ git add .$ git commit --message "Test and build on every push"$ git push
Ich arbeite mit

GitHub

Öffne dein Repository auf GitHub und geh auf den Reiter Actions. Der oberste Lauf gehört zu deinem Push. Öffne ihn, und du siehst die zwei Jobs: erst test, und sobald der fertig ist, build. Ein Klick auf einen Job zeigt jeden Schritt und was er ausgegeben hat. Der ganze Lauf dauert meist ein bis zwei Minuten und endet mit einem grünen Haken.

GitLab

Öffne dein Projekt auf GitLab und geh auf Build → Pipelines. Die oberste Pipeline gehört zu deinem Push. Öffne sie, und du siehst die zwei Stages: erst test, und sobald die fertig ist, build. Ein Klick auf einen Job zeigt, was er ausgegeben hat. Die ganze Pipeline dauert meist ein bis zwei Minuten und endet mit einem grünen Haken.

Wo das Image gelandet ist

Ich arbeite mit

GitHub

GitHub nennt das, was in seiner Registry liegt, Packages. Öffne dein Profil und dort den Reiter Packages: Da gibt es jetzt ein Paket guestbook und darin das Image unter seinen zwei Namen, der langen Commit-ID und production. Ein neues Paket ist zunächst privat: Niemand außer dir kann das Image holen. So soll es bleiben, und Teil 5 gibt dem Server einen Schlüssel dafür.

GitLab

Geh in deinem Projekt auf Deploy → Container Registry. Dort liegt jetzt ein Image unter seinen zwei Namen: der langen Commit-ID und production. Der Knopf daneben kopiert die volle Adresse des Images, die mit registry.gitlab.com anfängt und mit deinem Namen und dem Projekt weitergeht. Die Registry ist so privat wie das Projekt, und Teil 5 gibt dem Server einen Schlüssel dafür.

Ein fehlschlagender Test stoppt alles

Die Tests laufen aus gutem Grund zuerst. Um das zu sehen, mach absichtlich einen kaputt. Ändere in test/entries.test.js den Text, den der zweite Test erwartet, von 'Please write a message.' in 'Please write something.'. Die App sagt weiter den alten Satz, also schlägt der Test jetzt fehl. Push das:

~/projects/guestbook
$ git commit --all --message "Break a test on purpose"$ git push

Schau dir die Pipeline noch einmal an. Sie wird bei test rot, und build startet gar nicht. In der Registry hat sich nichts geändert: production zeigt weiter auf das Image von vorhin. Eine Version, deren Tests fehlschlagen, bekommt nie ein Image, also kann sie den Server nie erreichen. Das ist das erste Sicherheitsnetz dieser Serie, und weitere folgen.

Nimm die Änderung zurück. git revert macht einen neuen Commit, der den letzten rückgängig macht:

~/projects/guestbook
$ git revert --no-edit HEAD$ git push

Die Pipeline ist wieder grün, und production ist zum Image dieses neuesten Commits weitergewandert.

Was du jetzt hast

Jeder Push auf main wird getestet, und jede Version, die besteht, wartet als Image in der Registry, auffindbar über ihre Commit-ID, und das neueste heißt production. Noch holt es niemand ab. Im nächsten Teil richtest du den Server ein, der das tun wird: eine kleine eigene Maschine, abgesichert, mit Docker und einem Schlüssel, der die Registry lesen kann und sonst nichts.

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.