Deployments ohne Ausfall für Node-Apps mit Docker Compose · Teil 1 von 11 der Serie
Teil 1: Ein Gästebuch, das sich zu deployen lohnt
Sieh dir an, wie die ganze Pipeline funktionieren wird, und bau dann die kleine App, die sie ausliefert: ein Gästebuch mit Node.js und einer PostgreSQL-Datenbank, einem Test und einem ersten Commit auf GitHub oder GitLab.
Deployments ohne Ausfall für Node-Apps mit Docker ComposeTeil 1 von 11
Auf dieser Seite
Quest-Ziele
- Verstehen, warum ein normales Update eine Website kurz offline nimmt
- Die fünf Schritte der Pipeline kennen, die diese Serie baut
- PostgreSQL mit Docker Compose in einem Container betreiben
- Eine kleine Web-App mit Node.js und Hono bauen, die ihre Einträge in der Datenbank speichert
- Die Datenbank mit einer Migration ändern und deinen Code mit einem Test prüfen
- Das Projekt auf GitHub oder GitLab pushen
Eine Website zu aktualisieren, läuft meistens so: alte Version stoppen, neue starten. Dazwischen ist eine Lücke. Sie dauert eine Sekunde oder zwanzig, und wer genau dann vorbeikommt, sieht eine Fehlerseite. Also hebt man sich Updates für den Abend auf, erledigt sie in Eile und fürchtet sie ein bisschen.
Das muss nicht sein. In dieser Serie baust du eine kleine Pipeline, in der es diese Lücke nicht gibt: Du pushst deinen Code, und ein, zwei Minuten später ist die neue Version online, ohne dass ein einziger Besucher etwas merkt. Besondere Werkzeuge brauchst du dafür nicht, nur Docker Compose, ein kurzes Skript und GitHub oder GitLab.
Der Plan
Wenn die Serie fertig ist, passiert bei jedem Push in dein Repository das:
Die Pipeline testet und baut. GitHub oder GitLab führt deine Tests aus. Bestehen sie, wird die App in ein Image gepackt, ein Paket mit der App und allem, was sie zum Laufen braucht.
Das Image kommt ins Regal. Beide Plattformen bewahren Images für dich auf. Das neueste bekommt das Etikett
production.Der Server schaut ins Regal. Einmal pro Minute fragt dein Server, ob
productionein neues Image ist. Niemand meldet sich am Server an, und die Pipeline hat keinen Schlüssel zu ihm.Der Server tauscht ohne Lücke. Er startet die neue Version neben der alten, wartet, bis die neue beweist, dass sie funktioniert, schickt die Besucher dorthin und lässt erst dann die alte zu Ende arbeiten und gehen.
Wenn etwas nicht stimmt, bleibt die alte Version. Eine neue Version, die nicht richtig startet, sieht nie einen Besucher, und eine, die sich später als schlecht herausstellt, lässt sich mit einem Klick zurücknehmen.
Die Serie baut das von innen nach außen. Die Teile 1 bis 3 machen die App und ihr Image. Teil 4 bringt die Pipeline, die Teile 5 und 6 den Server. Teil 7 ist das Herzstück, der Tausch ohne Lücke, und in Teil 8 erledigt der Server ihn von selbst. In den Teilen 9 bis 11 geht es um die Tage, an denen etwas schiefgeht: fehlgeschlagene Deployments, Änderungen an der Datenbank und eine Nachricht, die dir sagt, was passiert ist.
Was du brauchst
Node.js, Version 26 oder neuer.
Docker mit Docker Compose. Docker Desktop bringt beides mit, unter Linux die normalen Docker-Pakete.
Git und ein Konto bei GitHub oder GitLab. Die kostenlosen Tarife reichen.
Ein Terminal. Die Befehle sind für Linux und macOS geschrieben. Unter Windows nimmst du WSL, das dir ein Linux-Terminal gibt.
Prüf, was du hast:
$ node --versionv26.13.0$ docker --versionDocker version 29.9.2, build a82e528$ git --versiongit version 2.53.0
Ab Teil 5 brauchst du außerdem einen kleinen gemieteten Server, der ein paar Euro im Monat kostet, und eine Domain oder Subdomain, die du auf ihn zeigen lassen kannst. Bis dahin passiert alles auf deinem eigenen Rechner.
GitHub oder GitLab?
Die Serie funktioniert mit beiden, und bei den meisten Schritten macht es keinen Unterschied. Wo doch, findest du einen Umschalter wie den hier unten. Wähl deine Plattform einmal aus: Die Wahl bleibt gespeichert, auf jeder Seite der Serie.
Leg als Erstes ein leeres Repository für das Projekt an:
GitHub
Klick auf GitHub oben rechts auf das + und wähl New repository. Nenn es guestbook, stell es auf Private und lass alles andere, wie es ist: kein README, keine .gitignore, keine Lizenz. Das Repository muss leer sein, weil du am Ende dieses Teils deinen eigenen ersten Commit dorthin pushst.
GitLab
Klick auf GitLab oben links auf das + und wähl New project/repository, dann Create blank project. Nenn es guestbook, stell die Sichtbarkeit auf Private und entfern den Haken bei Initialize repository with a README. Das Repository muss leer sein, weil du am Ende dieses Teils deinen eigenen ersten Commit dorthin pushst.
Das Projekt
Die App ist ein Gästebuch: Besucher hinterlassen ihren Namen und eine Nachricht, und die Seite zeigt, was andere geschrieben haben. Das ist klein genug, um es in ein paar Minuten zu lesen, und es hat, was ein Deployment interessant macht: eine Datenbank, die nichts verlieren darf, und Anfragen, die nicht abgeschnitten werden dürfen.
Leg dort, wo deine Projekte liegen (die Serie nimmt ~/projects), einen Ordner dafür an, mit Git und drei Unterordnern:
$ mkdir guestbook && cd guestbook$ git init --initial-branch=main$ mkdir src migrations test
Leg im neuen Ordner package.json an:
{
"name": "guestbook",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "node --env-file=.env --watch src/server.js",
"migrate": "node --env-file=.env src/migrate.js",
"start": "node src/server.js",
"test": "node --test"
},
"dependencies": {
"@hono/node-server": "^2.1.9",
"hono": "^4.13.19",
"pg": "^8.23.1"
}
}"type": "module" erlaubt den Dateien import und export. Die App ist reines JavaScript, es gibt also nichts zu kompilieren. Die vier Skripte sind Abkürzungen:
npm run devstartet die App zum Arbeiten: Es liest die Einstellungen aus einer Datei namens.envund startet neu, sobald du eine Datei speicherst.npm run migratebringt die Datenbank auf den neuesten Stand. Dazu gleich mehr.npm startstartet die App ohne alle Extras.npm testführt die Tests aus, mit dem Test-Runner, der in Node.js eingebaut ist.
Die App braucht drei Pakete: Hono, ein kleines Framework für Web-Apps, @hono/node-server, mit dem Hono auf Node.js läuft, und pg, das mit PostgreSQL spricht. Installier sie:
$ npm installadded 16 packages, and audited 17 packages in 995msfound 0 vulnerabilities
npm hat dabei auch eine Datei namens package-lock.json geschrieben. Sie hält die genaue Version jedes Pakets fest, damit die Pipeline und der Server später genau das installieren, was du jetzt hast. Sie gehört ins Repository. Zwei andere Dinge gehören nicht hinein, und .gitignore hält sie draußen:
node_modules
.envDie Datenbank
Die Einträge liegen in PostgreSQL, einer Datenbank. Installieren musst du sie nicht: Sie läuft in einem Container, einem Programm, das vom Rest deines Rechners abgeschirmt ist und alles mitbringt, was es braucht. Docker Compose startet Container nach einer Beschreibung in einer Datei. Leg compose.yml an:
services:
db:
image: postgres:18-alpine
ports:
- '5432:5432'
environment:
POSTGRES_USER: guestbook
POSTGRES_PASSWORD: guestbook
POSTGRES_DB: guestbook
volumes:
- db-data:/var/lib/postgresql
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U guestbook']
interval: 5s
timeout: 3s
retries: 10
volumes:
db-data:Das beschreibt einen Service namens db:
imageist, was laufen soll: PostgreSQL 18.portsmacht die Datenbank von deinem Rechner aus erreichbar, auf Port 5432.environmentlegt den Benutzer, das Passwort und den Namen der Datenbank fest, die beim ersten Start angelegt wird. Ein Passwort wie dieses ist auf deinem eigenen Rechner in Ordnung. Der Server bekommt ein richtiges.volumesgibt den Daten einen Platz außerhalb des Containers, damit sie erhalten bleiben, wenn der Container ersetzt wird.healthcheckfragt die Datenbank alle fünf Sekunden, ob sie bereit ist. Wozu das gut ist, siehst du in Teil 3.
Die App muss wissen, wo die Datenbank ist. Sie liest das aus einer Umgebungsvariable, und auf deinem Rechner kommt die Variable aus der Datei .env:
DATABASE_URL=postgres://guestbook:guestbook@localhost:5432/guestbookDie Adresse nennt den Benutzer, das Passwort, den Rechner, den Port und die Datenbank. Solche Einstellungen unterscheiden sich zwischen deinem Rechner und dem Server, deshalb stehen sie nicht im Code und nicht in Git.
Eine neue Datenbank ist leer. Die Tabelle für die Einträge legt eine Migration an: eine nummerierte Datei mit einer Änderung an der Datenbank, die genau einmal läuft. Leg migrations/001-create-entries.sql an:
create table entries (
id serial primary key,
name text not null,
message text not null,
created_at timestamptz not null default now()
);Jede spätere Änderung an der Datenbank wird eine weitere Datei in diesem Ordner sein. Ein kleines Skript führt die aus, die noch nicht gelaufen sind. Leg src/migrate.js an:
import { readdir, readFile } from 'node:fs/promises';
import { pool } from './db.js';
/**
* Brings the database up to date: runs every file in migrations/ that has not run yet, in
* the order of their names, and notes each one in the table "migrations".
*/
const folder = new URL('../migrations/', import.meta.url);
await pool.query(
'create table if not exists migrations (name text primary key, applied_at timestamptz not null default now())',
);
const { rows } = await pool.query('select name from migrations');
const applied = new Set(rows.map((row) => row.name));
const files = (await readdir(folder)).filter((name) => name.endsWith('.sql')).sort();
for (const name of files) {
if (applied.has(name)) continue;
const sql = await readFile(new URL(name, folder), 'utf8');
const client = await pool.connect();
try {
// All or nothing: a migration that fails halfway leaves no trace.
await client.query('begin');
await client.query(sql);
await client.query('insert into migrations (name) values ($1)', [name]);
await client.query('commit');
console.log(`Applied ${name}`);
} catch (error) {
await client.query('rollback');
throw error;
} finally {
client.release();
}
}
console.log('Database is up to date');
await pool.end();Das Skript führt selbst Buch, in einer Tabelle namens migrations. Es liest den Ordner, sortiert die Dateien nach Namen, überspringt die notierten und führt den Rest aus. Jede läuft in einer Transaktion, zwischen begin und commit: Schlägt irgendetwas in der Datei fehl, bleibt die Datenbank genau so, wie sie vorher war. Du kannst das Skript so oft ausführen, wie du willst. Das ist wichtig, denn ab Teil 7 führt der Server es vor jedem Deployment aus.
Es importiert pool aus einer Datei, die es noch nicht gibt. Leg src/db.js an:
import pg from 'pg';
/** A pool keeps a few connections to the database open and hands them out per query. */
export const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
export async function listEntries() {
const { rows } = await pool.query(
'select name, message, created_at from entries order by created_at desc limit 50',
);
return rows;
}
export async function addEntry({ name, message }) {
await pool.query('insert into entries (name, message) values ($1, $2)', [name, message]);
}Das ist alles, was die App je von der Datenbank will: die neuesten fünfzig Einträge, und einen hinzufügen. $1 und $2 sind Platzhalter. Die Werte reisen getrennt von der Abfrage, also kann ein Besucher keinen eigenen Befehl hineinschmuggeln.
Starte die Datenbank und führ die Migration aus:
$ docker compose up --detach$ npm run migrate> guestbook@1.0.0 migrate> node --env-file=.env src/migrate.jsApplied 001-create-entries.sqlDatabase is up to date
Die App
Vier kurze Dateien fehlen noch. Die erste entscheidet, ob ein Eintrag in Ordnung ist. Leg src/entries.js an:
/** Checks what a visitor sent. Returns the cleaned entry, or the reason it was refused. */
export function cleanEntry(input) {
const name = String(input.name ?? '').trim();
const message = String(input.message ?? '').trim();
if (!name) return { error: 'Please tell us your name.' };
if (name.length > 40) return { error: 'Your name can have up to 40 characters.' };
if (!message) return { error: 'Please write a message.' };
if (message.length > 500) return { error: 'Your message can have up to 500 characters.' };
return { entry: { name, message } };
}Das ist das eine Stück echte Logik in der App, und es ist mit Absicht von der Datenbank und vom Web getrennt: Eine Funktion, die nur einen Wert nimmt und einen Wert zurückgibt, lässt sich in einer Millisekunde testen.
Als Nächstes die Seite. Leg src/page.js an:
import { html } from 'hono/html';
/** The whole page. `html` escapes everything it is given, so a visitor cannot sneak in markup. */
export const page = ({ entries, error, version }) => html`<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Guestbook</title>
<style>
body { font-family: system-ui, sans-serif; max-width: 36rem; margin: 2rem auto; padding: 0 1rem; }
form { display: grid; gap: 0.5rem; margin-bottom: 2rem; }
input, textarea, button { font: inherit; padding: 0.5rem; }
li { margin-bottom: 1rem; }
.error { color: #b91c1c; }
footer { color: #6b7280; font-size: 0.875rem; }
</style>
</head>
<body>
<h1>Guestbook</h1>
<form method="post" action="/entries">
<input name="name" placeholder="Your name" maxlength="40" required />
<textarea name="message" placeholder="Your message" maxlength="500" required></textarea>
<button>Sign the guestbook</button>
${error ? html`<p class="error">${error}</p>` : ''}
</form>
<ul>
${entries.map(
(entry) => html`<li><strong>${entry.name}</strong> wrote:<br />${entry.message}</li>`,
)}
</ul>
<footer>Version ${version}</footer>
</body>
</html>`;Eine Funktion baut die ganze Seite: das Formular, die Liste der Einträge und eine Fußzeile mit einer Version. html kommt von Hono und maskiert jeden Wert, der in die Seite eingesetzt wird. Eine Nachricht, die <script> enthält, erscheint also als Text, statt in den Browsern anderer Besucher zu laufen.
Die App selbst verbindet die beiden. Leg src/app.js an:
import { Hono } from 'hono';
import { addEntry, listEntries } from './db.js';
import { cleanEntry } from './entries.js';
import { page } from './page.js';
/** Which build this is. The pipeline bakes the commit into the image; locally it is "dev". */
const version = (process.env.APP_VERSION ?? 'dev').slice(0, 7);
export const app = new Hono();
app.get('/', async (c) => c.html(page({ entries: await listEntries(), version })));
app.post('/entries', async (c) => {
const { entry, error } = cleanEntry(await c.req.parseBody());
if (error) return c.html(page({ entries: await listEntries(), error, version }), 400);
await addEntry(entry);
return c.redirect('/', 303);
});Zwei Adressen: Eine Anfrage an / bekommt die Seite mit den Einträgen, und das Formular schickt seinen Inhalt an /entries. Dort bringt ein Eintrag, den cleanEntry ablehnt, die Seite mit dem Grund zurück. Ein guter wird gespeichert, und der Browser wird zurück zur Seite geschickt. Die 303 sagt ihm, dass er die Seite neu holen soll, damit ein Neuladen das Formular nicht ein zweites Mal abschickt.
Schau dir die Zeile mit version an. Sie liest eine Umgebungsvariable namens APP_VERSION und behält ihre ersten sieben Zeichen. Die Pipeline schreibt dort später die ID des Commits hinein, und die Fußzeile der Seite zeigt sie. Immer wenn eine neue Version online geht, siehst du es also im Browser. Auf deinem Rechner ist die Variable nicht gesetzt, und in der Fußzeile steht dev.
Die letzte Datei startet den Server. Leg src/server.js an:
import { serve } from '@hono/node-server';
import { app } from './app.js';
const port = Number(process.env.PORT ?? 3000);
serve({ fetch: app.fetch, port }, () => {
console.log(`Guestbook listening on port ${port}`);
});Starte die App:
$ npm run dev> guestbook@1.0.0 dev> node --env-file=.env --watch src/server.jsGuestbook listening on port 3000
Öffne localhost:3000 und trag dich in dein Gästebuch ein:
Das Terminal ist jetzt mit der App beschäftigt. Öffne für die nächsten Befehle ein zweites im selben Ordner, oder beende die App mit Strg+C.
Ein Test
Eine Pipeline, die von selbst ausliefert, braucht etwas, das ihr sagt, wenn der Code kaputt ist. Dafür sind Tests da. Leg test/entries.test.js an:
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { cleanEntry } from '../src/entries.js';
test('accepts a name and a message', () => {
const { entry } = cleanEntry({ name: ' Robin ', message: 'Hello!' });
assert.deepEqual(entry, { name: 'Robin', message: 'Hello!' });
});
test('refuses an empty message', () => {
const { error } = cleanEntry({ name: 'Robin', message: ' ' });
assert.equal(error, 'Please write a message.');
});
test('refuses a name that is too long', () => {
const { error } = cleanEntry({ name: 'x'.repeat(41), message: 'Hello!' });
assert.equal(error, 'Your name can have up to 40 characters.');
});Jeder Test ruft cleanEntry mit einem Beispiel auf und sagt, was herauskommen muss. Führ sie aus:
$ npm test> guestbook@1.0.0 test> node --test✔ accepts a name and a message (1.405265ms)✔ refuses an empty message (0.152699ms)✔ refuses a name that is too long (0.111174ms)ℹ tests 3ℹ suites 0ℹ pass 3ℹ fail 0ℹ cancelled 0ℹ skipped 0ℹ todo 0ℹ duration_ms 67.604609
Drei Tests sind nicht viel, aber es geht ums Prinzip: Die Pipeline wird genau diesen Befehl ausführen, bevor sie irgendetwas baut. Schlägt ein Test fehl, wird nichts ausgeliefert.
Der erste Commit
Nimm alles in Git auf:
$ git add .$ git commit --message "A guestbook"
Verbinde dann den Ordner mit dem leeren Repository, das du angelegt hast, und push. Ersetz your-name durch deinen Benutzernamen:
GitHub
$ git remote add origin git@github.com:your-name/guestbook.git$ git push --set-upstream origin main
Diese Adresse nutzt SSH, GitHub muss also deinen SSH-Schlüssel kennen. Wird der Push abgelehnt, hinterleg zuerst deinen Schlüssel in deinem Konto: GitHubs Anleitung zeigt, wie. Lad danach die Seite des Repositorys auf GitHub neu: Deine Dateien sind da.
GitLab
$ git remote add origin git@gitlab.com:your-name/guestbook.git$ git push --set-upstream origin main
Diese Adresse nutzt SSH, GitLab muss also deinen SSH-Schlüssel kennen. Wird der Push abgelehnt, hinterleg zuerst deinen Schlüssel in deinem Konto: GitLabs Anleitung zeigt, wie. Lad danach die Seite des Projekts auf GitLab neu: Deine Dateien sind da.
Was du jetzt hast
Eine kleine App mit einer Datenbank, einer Migration, einem Test und einem Repository, in das du pushen kannst. Sie läuft auf deinem Rechner, und bisher nur dort. Bevor sie sich ohne Lücke tauschen lässt, muss sie zwei Dinge lernen, die jedes Deployment von ihr verlangen wird: zu sagen, ob sie bereit für Besucher ist, und ihre Arbeit zu beenden, bevor sie geht. Das ist der nächste Teil.
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.
