Zum Inhalt springen

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

Teil 11: Eine Nachricht nach jedem Deployment

Der Server deployt von selbst, also schaut niemand zu. Lass das Deploy-Skript eine Zeile in deinen Chat schreiben, wenn eine Version live geht und wenn eine scheitert, und blick auf die ganze Pipeline zurück.

Quest-Ziele

  • Verstehen, was ein Webhook ist, und einen in Discord oder Slack anlegen
  • Mit curl eine Nachricht von der Kommandozeile aus schicken
  • Das Deploy-Skript jeden Erfolg und jeden Fehlschlag melden lassen
  • Dafür sorgen, dass ein ausgefallener Chat nie ein Deployment aufhält
  • Die ganze Pipeline am Stück sehen und wissen, wie es weitergehen kann

Dein Server holt sich neue Versionen selbst. Darum ging es in Teil 8, und es hat einen Preis: Niemand schaut zu. Die Pipeline wird grün, sobald das Image in der Registry liegt, lange bevor der Server irgendetwas damit gemacht hat. Wird die neue Version dann nie gesund, läuft die alte weiter, und genau das willst du. Der Grund aber steht in einem Log auf dem Server, bis jemand nachsieht.

Ein gescheitertes Deployment sollte zu dir kommen. Eine Zeile in einem Chat genügt, und sie kostet ein paar Zeilen Shell.

Ein Webhook

Ein Webhook ist eine Webadresse, die etwas mit dem anfängt, was man ihr schickt. Chat-Dienste vergeben solche Adressen für Kanäle: Schick einen kurzen Text an die Adresse, und er erscheint als Nachricht. Kein Konto für den Server, kein Bot, keine Bibliothek.

Dieser Teil benutzt Discord. Öffne in deinem Discord-Server die Servereinstellungen, geh zu Integrationen und klick auf Webhook erstellen (hat der Server schon Webhooks, steht der Knopf unter Webhooks und heißt Neuer Webhook). Gib ihm einen Namen wie Guestbook, wähle den Kanal, in dem die Nachrichten landen sollen, und kopiere die Webhook-URL.

Probier es auf dem Server aus, denn von dort kommen später die Nachrichten. Setze deine eigene Adresse an die Stelle der hier gezeigten:

deploy@guestbook: ~
$ curl --header "Content-Type: application/json" --data '{"content": "Hello from the server"}' "https://discord.com/api/webhooks/1234567890/AbCdEf..."

Der Befehl gibt nichts aus, und im Kanal erscheint Hello from the server. Geschickt hast du ein winziges Stück JSON mit einem Feld, content, dem Text der Nachricht.

Dem Skript beibringen

Öffne auf dem Server, in ~/guestbook, die Datei .env:

deploy@guestbook: ~/guestbook
$ nano .env

Füge eine Zeile hinzu, mit deiner Adresse:

.env
DISCORD_WEBHOOK=https://discord.com/api/webhooks/1234567890/AbCdEf...

Der Rest passiert auf deinem Computer, in deploy/deploy.sh. Drei Stellen ändern sich. Erstens eine neue Funktion notify, direkt nach der Zeile, die say definiert:

deploy/deploy.sh
# Posts a line to the chat, if a webhook is set in .env. A failed post never stops a deploy.
notify() {
  webhook=$(grep "^DISCORD_WEBHOOK=" .env | cut -d = -f 2-)
  if [ -z "$webhook" ]; then return; fi
  curl --silent --show-error --max-time 10 \
    --header "Content-Type: application/json" \
    --data "{\"content\": \"$1\"}" "$webhook" > /dev/null || true
}

Was sie tut:

  • Sie liest die Adresse aus der .env, so wie Schritt 1 den Namen des Images liest: grep findet die Zeile, cut nimmt, was auf das = folgt.

  • Ohne Adresse kehrt sie zurück und tut nichts. Das Skript funktioniert also auch auf einem Server, auf dem niemand eine gesetzt hat.

  • curl schickt die Nachricht, so wie du es eben von Hand getan hast. Es bleibt still, solange nichts schiefgeht, und gibt nach zehn Sekunden auf.

  • || true am Ende heißt: Was auch passiert ist, mach weiter. Ein Chat-Dienst, der gerade ausgefallen ist, darf nie ein Deployment aufhalten oder eines scheitern lassen, das gut gegangen ist.

Der Text steht im JSON zwischen Anführungszeichen, also halte deine Nachrichten frei von eigenen Anführungszeichen.

Zweitens bekommt die Funktion fail aus Teil 9 eine Zeile dazu. Ersetze sie durch diese:

deploy/deploy.sh
fail() {
  say "$1"
  echo "$wanted" > .failed
  notify ":x: Guestbook: $1"
  exit 1
}

Die beiden Fehler, die das Skript behandelt, laufen durch diese Funktion: eine Datenbankänderung, die nicht funktioniert, und ein neuer Container, der nie gesund wird. Beide erreichen jetzt deinen Chat, mit ihrem Grund. Und weil sich das Skript ein gescheitertes Image merkt, bekommst du eine Nachricht pro kaputter Version und nicht eine pro Minute.

Drittens die gute Nachricht. Ersetze die letzte Zeile des Skripts, die meldet, dass die Version live ist, durch diese drei:

deploy/deploy.sh
version=$(docker exec "$new" printenv APP_VERSION | cut -c 1-7)
say "Version $version is live"
notify ":white_check_mark: Guestbook: version $version is live"

Die Version steht jetzt in einer Variablen, weil sie zweimal gebraucht wird: für das Log und für den Chat. :x: und :white_check_mark: sind die Namen zweier Emoji. Der Chat zeigt sie als rotes Kreuz und als grünen Haken, so erkennst du die beiden Arten von Nachricht, ohne sie zu lesen.

Das ganze Skript

Das ist deploy/deploy.sh, wie es am Ende der Serie aussieht. Vergleiche deines damit:

deploy/deploy.sh
#!/bin/sh
# Brings the newest image online without a gap: the new container starts beside the old
# one, has to prove it is healthy, gets the visitors, and only then the old one leaves.
set -eu
cd "$(dirname "$0")"
# Compose reports every step it takes. The log should hold only what matters.
export COMPOSE_PROGRESS=quiet

say() { echo "$(date +%H:%M:%S) $*"; }

# Posts a line to the chat, if a webhook is set in .env. A failed post never stops a deploy.
notify() {
  webhook=$(grep "^DISCORD_WEBHOOK=" .env | cut -d = -f 2-)
  if [ -z "$webhook" ]; then return; fi
  curl --silent --show-error --max-time 10 \
    --header "Content-Type: application/json" \
    --data "{\"content\": \"$1\"}" "$webhook" > /dev/null || true
}

# 1. Fetch the image the registry calls "production" and compare it with what is running.
docker compose pull --quiet web
image=$(grep "^IMAGE=" .env | cut -d = -f 2-):production
wanted=$(docker image inspect --format '{{.Id}}' "$image")
old=$(docker compose ps --quiet web)
running=""
if [ -n "$old" ]; then running=$(docker inspect --format '{{.Image}}' "$old"); fi

if [ "$wanted" = "$running" ]; then
  say "Nothing new"
  exit 0
fi

# An image that failed before is not tried again every minute.
if [ "$wanted" = "$(cat .failed 2> /dev/null || true)" ]; then
  say "Still the image that failed, waiting for a new one"
  exit 0
fi

fail() {
  say "$1"
  echo "$wanted" > .failed
  notify ":x: Guestbook: $1"
  exit 1
}

# 2. Bring the database up to date, with the new image's migrations.
say "New image found, updating the database"
docker compose run --rm -T web node src/migrate.js || fail "The database update failed, the old version keeps running"

# 3. Start a container from the new image beside the old one.
say "Starting the new container"
count=$(echo $old | wc -w)
docker compose up --detach --no-deps --no-recreate --scale web=$((count + 1)) web
new=$(docker compose ps --quiet web | grep --invert-match --fixed-strings "${old:-none}")

# 4. Wait until it reports healthy, for a minute at most.
status=starting
for attempt in $(seq 1 30); do
  status=$(docker inspect --format '{{.State.Health.Status}}' "$new")
  if [ "$status" = healthy ]; then break; fi
  sleep 2
done

if [ "$status" != healthy ]; then
  docker logs --tail 20 "$new"
  docker rm --force "$new" > /dev/null
  fail "The new container did not get healthy, the old version keeps running"
fi

# 5. Send the visitors to the new container.
name=$(docker inspect --format '{{.Name}}' "$new" | cut -c 2-)
echo "reverse_proxy $name:3000" > caddy/upstream.caddy
docker compose up --detach caddy
docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile
say "Visitors now reach $name"

# 6. Let the old container finish its open requests, then remove it.
if [ -n "$old" ]; then
  docker stop "$old" > /dev/null
  docker rm "$old" > /dev/null
fi
docker image prune --force > /dev/null
rm -f .failed

version=$(docker exec "$new" printenv APP_VERSION | cut -c 1-7)
say "Version $version is live"
notify ":white_check_mark: Guestbook: version $version is live"

Kopiere es auf den Server, wie gehabt:

~/projects/guestbook
$ scp deploy/deploy.sh deploy@guestbook.example.com:guestbook/

Der Timer benutzt das neue Skript bei seinem nächsten Lauf. Nichts muss neu gestartet werden.

Probier es aus

Jede kleine Änderung genügt. Schreib in src/page.js den Satz Thank you for visiting. in die Fußzeile, vor das Wort Version. Dann:

~/projects/guestbook
$ git commit --all --message "Thank the visitors"$ git push

Leg das Terminal weg. Ein, zwei Minuten nachdem die Pipeline fertig ist, zeigt dein Chat einen grünen Haken und die Zeile Guestbook: version … is live, mit den ersten sieben Zeichen deines Commits. Das ist der ganze Weg, von deiner Tastatur zu deinen Besuchern und zurück zu dir, ohne dass du dich irgendwo eingeloggt hast.

Willst du auch die andere Nachricht sehen, dann mach den Health Check noch einmal kaputt wie in Teil 9. Etwa eine Minute nachdem der Server das Image gefunden hat, kommt ein rotes Kreuz mit The new container did not get healthy, the old version keeps running. Nimm die Änderung danach mit git revert zurück, wie dort.

Was du gebaut hast

Die ganze Serie in einem Bild: Der neue Container wird neben den alten gesetzt, und die Besucher hören nie auf zu kommen.
Die ganze Serie in einem Bild: Der neue Container wird neben den alten gesetzt, und die Besucher hören nie auf zu kommen.

Schau zurück auf das, was jetzt zwischen deiner Tastatur und deinen Besuchern steht:

  • eine App, die sagen kann, ob sie gesund ist, und die ihre offenen Anfragen beendet, bevor sie geht;

  • eine Pipeline auf GitHub oder GitLab, die jeden Push testet, ein Image daraus baut und es unter seinem Commit in der Registry aufbewahrt;

  • ein Server mit Docker, das ohne root läuft, einer Firewall und Caddy davor, der sich selbst um HTTPS kümmert;

  • ein Server, der sich neue Versionen selbst holt, sodass nirgendwo sonst ein Schlüssel zu ihm liegt;

  • ein Tausch, bei dem sich der neue Container beweisen muss, bevor ihn ein einziger Besucher erreicht, und der alte erst danach geht;

  • Sicherheitsnetze: Tests, die den Build stoppen, ein Health Check, der den Tausch stoppt, und ein Weg zurück zu jeder älteren Version, indem du einen Tag verschiebst;

  • ein Muster, um die Datenbank in Schritten zu ändern, die jede laufende Version übersteht;

  • und eine Nachricht, die dir sagt, wie jedes Deployment gelaufen ist.

Nichts davon ist ein Produkt, das du kaufen musstest, oder ein Framework, dem du vertrauen musst. Es sind ein oder zwei Dateien für die Pipeline, eine Compose-Datei, ein paar Zeilen für Caddy und ein Shell-Skript, das du von oben bis unten gelesen hast.

Wie es weitergehen kann

  • Backups nach Plan. Die pg_dump-Zeile aus Teil 10 in einem kleinen Skript, gestartet von einem Timer wie dem aus Teil 8, einmal pro Nacht. Ein Backup, das auf demselben Server liegt, hilft nur halb, also kopiere es auch woandershin.

  • Eine Testumgebung. Eine zweite Kopie des Stacks mit eigener Domain und eigenem Tag neben production, in der du dir eine Version ansehen kannst, bevor deine Besucher sie bekommen.

  • Mehr Tests. Jeder Test, den du der Pipeline hinzufügst, ist ein Fehler, der den Server nicht mehr erreichen kann.

  • Deine eigene App. Das Gästebuch war nur das Beispiel. Um eine andere Node.js-App so zu deployen, braucht sie drei Dinge: eine Adresse wie /health, die sagt, ob sie bereit ist, einen Handler für SIGTERM, der sie ihre Arbeit beenden lässt, und ein Dockerfile. Alles andere hast du schon gebaut.

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.