MariaDB-Kurs / Eine lokale Lernumgebung mit Docker Compose erstellen

Docker Compose beschreibt einen MariaDB-Container, seinen Verbindungsport und dauerhaften Speicher gemeinsam in einer Datei. So entsteht eine getrennte Lernumgebung, ohne einen MariaDB-Dienst direkt auf dem Computer zu installieren. Das Entfernen des Containers und das Entfernen seines Datenvolumes haben unterschiedliche Folgen.

Die Lernumgebung und ihre Voraussetzungen prüfen

Docker führt Anwendungen in Containern aus. Compose beschreibt deren Konfiguration in YAML, einem strukturierten Textformat. Dieser Aufbau veröffentlicht einen Datenbankzugang unter 127.0.0.1:3307. Der gesonderte Hostport ermöglicht den Betrieb neben einem Server auf 3306. Die Übung zu lokalen und entfernten Verbindungen unterscheidet die Netzwerkwege; die Sicherungsübung erklärt die vom Datenvolume getrennte Aufbewahrung.

Installieren Sie Docker Engine mit Compose-Plugin oder Docker Desktop nach den offiziellen Compose-Installationsanweisungen. Verwenden Sie unter Windows Linux-Container. Starten Sie Docker und prüfen Sie im Terminal beide Befehle, bevor Sie die Datenbank vorbereiten:

docker version
docker compose version

Die Konfiguration verwendet ausdrücklich die Imagefamilie mariadb:11.8. Dieser Tag kann künftig eine neuere Wartungsversion bezeichnen. Halten Sie bei exakt reproduzierbaren Umgebungen einen freigegebenen Patch-Tag oder Digest, die Kennung des Imageinhalts, fest. Die Prüfung von YAML-Struktur und SQL ersetzt keinen Test von Containerstart, Zustandsprüfung und Volume-Persistenz im Docker-System.

Projekt und Passwortdateien anlegen

  1. Erstellen Sie einen neuen Ordner mariadb-appops und öffnen Sie das Terminal darin. Führen Sie die Befehle nicht aus einem fremden Compose-Projekt aus.
  2. Legen Sie den Unterordner secrets mit den UTF-8-Dateien root-password.txt und app-password.txt an. Speichern Sie je ein unterschiedliches Übungspasswort ohne zusätzliche Erklärung. Die Dateien dürfen nicht leer bleiben.
  3. Speichern Sie die vollständige Konfiguration des folgenden Abschnitts als compose.yaml. Erstellen Sie außerdem eine .gitignore mit den folgenden zwei Zeilen und begrenzen Sie den Dateizugriff auf die Passwörter.
secrets/
.env

Compose-Secrets stellen Dateien ausgewählten Diensten bereit. Die lokalen Quelldateien werden dadurch nicht zu einem verschlüsselten Passworttresor. Schützen Sie die Dateien und den Docker-Zugang. Die offizielle Dokumentation zu Compose-Secrets erläutert Einbindungen und die Voraussetzung von Linux-Containern.

Die vollständige Compose-Konfiguration verstehen

name: mariadb-appops
services:
  db:
    image: mariadb:11.8
    ports:
      - "127.0.0.1:3307:3306"
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/root_password
      MARIADB_DATABASE: appops_lab
      MARIADB_USER: app_user
      MARIADB_PASSWORD_FILE: /run/secrets/app_password
    secrets:
      - root_password
      - app_password
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
secrets:
  root_password:
    file: ./secrets/root-password.txt
  app_password:
    file: ./secrets/app-password.txt
volumes:
  db_data:

Auf dem Computer wird Port 3307 veröffentlicht, im Container verwendet MariaDB 3306. Ein Client auf dem Host verbindet sich mit 127.0.0.1:3307; ein anderer Dienst im selben Compose-Netzwerk verwendet db:3306. Die Bindung an die Loopbackadresse des Hosts begrenzt den veröffentlichten Übungszugang auf diesen lokalen Netzwerkweg.

Das benannte Volume db_data enthält das Datenverzeichnis. Variablen mit _FILE verweisen auf Passwortdateien. Die offizielle Referenz der MariaDB-Imagevariablen beschreibt die erstmalige Erstellung von Datenbank und Konto bei neuem Datenverzeichnis. Das Ändern einer Passwortdatei ändert ein bereits im initialisierten Volume gespeichertes Konto nicht automatisch.

Das offizielle Skript healthcheck.sh prüft Verbindung und InnoDB-Initialisierung. Ein laufender Container allein belegt noch keinen für die Übungsabfragen bereiten Datenbankserver.

Dienst starten und einen gespeicherten Datensatz prüfen

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=80 db

Der erste Befehl prüft die Konfiguration mit Compose. Kontrollieren Sie anschließend den Zustand healthy und bei Problemen das Initialisierungsprotokoll. Korrigieren Sie fehlende Secret-Dateien oder einen belegten Hostport vor einer Wiederholung. Prüfen Sie Protokolle vor dem Teilen auf sensible Inhalte.

docker compose exec db mariadb --default-character-set=utf8mb4 -u app_user -p appops_lab

Geben Sie das Passwort aus app-password.txt an der Abfrage ein. Führen Sie im SQL-Client den folgenden vollständigen Block aus; er liefert einen Datensatz. Die Tabellenerstellung gilt für den ersten Durchlauf. Besteht die Tabelle schon, untersuchen Sie den vorhandenen Übungsstand, statt den Aufbau ungeprüft zu wiederholen.

USE appops_lab;
CREATE TABLE docker_notes (
  note_id INT NOT NULL PRIMARY KEY,
  note_text VARCHAR(80) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO docker_notes VALUES (1, 'volume survives container replacement');
SELECT note_id, note_text FROM docker_notes;

Der gespeicherte englische Text bedeutet „Das Volume überlebt den Austausch des Containers“ und bleibt als Übungsliteral unverändert. Sein Vorhandensein nach dem Containeraustausch dient anschließend als Persistenzprüfung.

Ist auf dem Computer ein mariadb-Client installiert, erreicht der folgende Befehl denselben Server über den veröffentlichten Hostport. Port 3306 könnte stattdessen zu einem anderen lokalen Server führen:

mariadb --protocol=tcp --host=127.0.0.1 --port=3307 --default-character-set=utf8mb4 -u app_user -p appops_lab

Den Container austauschen und das Volume erhalten

docker compose down
docker compose up -d

Bei dieser Konfiguration entfernt down ohne Zusatzoptionen Container und Projektnetzwerk, erhält aber das benannte Datenvolume. Warten Sie, bis der neue Dienst healthy ist, verbinden Sie sich erneut und führen Sie SELECT * FROM docker_notes; aus. Der zuvor eingefügte Datensatz soll weiterhin vorhanden sein. Erst die erneute Abfrage prüft den gespeicherten Zustand.

docker compose down --volumes entfernt zusätzlich Volumes und kann die Datenbank verwerfen. Verwenden Sie es nur, wenn die Übungsdaten dieses Projekts ausdrücklich entbehrlich sind. Es ist kein gewöhnlicher Neustartbefehl. Für aufzubewahrende Daten benötigen Sie die Datenbanksicherung zusätzlich zum Volume. Die offizielle Compose-down-Referenz erläutert den Löschumfang.

Fehler eingrenzen, bevor Daten neu initialisiert werden

Symptom Prüfung
Docker nicht erreichbar Laufende Engine beziehungsweise Docker Desktop und ausgewählter Docker-Kontext
Veröffentlichter Port belegt Hostport 3307; nach Änderung auch den Clientport anpassen
Access denied Bei der Initialisierung verwendetes Konto und Passwort sowie zuvor bestehendes Volume
Container läuft, SQL ist nicht verfügbar Zustand, Initialisierungsprotokoll und Unterschied zwischen db im Projektnetz und 127.0.0.1 auf dem Host
Unerwartete Daten nach Austausch Projektname mariadb-appops, Arbeitsordner, Verbindungsport und eingebundenes Volume

Entfernen Sie das Volume nicht als ersten Diagnoseschritt. Identifizieren Sie Server und Datenverzeichnis und entscheiden Sie anschließend, ob eine Konfigurationskorrektur oder eine bewusst neue Initialisierung erforderlich ist.