Cours MariaDB / Créer un environnement Docker Compose avec stockage persistant

Docker Compose permet de décrire dans un fichier un conteneur MariaDB, son port de connexion et son stockage persistant. Vous obtenez ainsi un environnement d’apprentissage distinct sans installer un service de base de données sur votre PC ; supprimer le conteneur et supprimer son volume de données ont toutefois des conséquences différentes.

Définir l’environnement et vérifier les prérequis

Docker exécute l’application dans un conteneur ; Compose décrit sa configuration d’exécution dans un fichier YAML. Cet exercice lance une seule base, accessible depuis votre ordinateur à l’adresse 127.0.0.1:3307. Ce port distinct permet de conserver un éventuel serveur local utilisant déjà le port 3306. Le guide des connexions locales et distantes aide à identifier le serveur réellement contacté.

Installez Docker Engine avec le plugin Compose ou Docker Desktop en suivant les instructions officielles d’installation de Compose. Sous Windows, utilisez des conteneurs Linux. Démarrez le moteur Docker et vérifiez que les deux commandes suivantes fonctionnent :

docker version
docker compose version

La première doit permettre de contacter le serveur Docker, pas seulement d’afficher la version du client. La seconde confirme la disponibilité de Compose. L’exemple choisit la famille d’images mariadb:11.8. Ce tag peut désigner une nouvelle version corrective au fil du temps ; consignez un tag correctif approuvé ou un digest si vous devez reproduire exactement la même image. Les étapes ci-dessous permettent de vérifier le démarrage, l’état de santé et la persistance dans votre environnement Docker.

Préparer le projet et les fichiers de mots de passe

  1. Créez un nouveau dossier mariadb-appops et ouvrez-y votre terminal. Vérifiez que ce nom de projet n’est pas déjà utilisé ; sinon, choisissez un autre nom dans le dossier et dans la configuration. N’exécutez pas ces commandes depuis un projet Compose sans rapport.
  2. Créez un sous-dossier secrets avec les fichiers root-password.txt et app-password.txt. Chacun contient un seul mot de passe d’exercice différent, en texte UTF-8, sans commentaire ni valeur vide.
  3. Enregistrez la configuration complète de la section suivante dans compose.yaml. Ajoutez les deux lignes ci-dessous à un fichier .gitignore, puis limitez l’accès local aux fichiers sensibles.
secrets/
.env

Les secrets Compose rendent les fichiers accessibles uniquement aux services auxquels ils sont accordés. Ils ne transforment pas les fichiers sources locaux en coffre-fort chiffré. Protégez ces fichiers et l’accès à Docker ; le .gitignore n’efface pas un secret déjà enregistré dans l’historique Git. La documentation des secrets Compose explique leur montage dans les conteneurs Linux.

Comprendre la configuration Compose complète

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:

Le port 3307 appartient à l’ordinateur hôte ; le serveur écoute sur 3306 dans le conteneur. Un client installé sur le PC utilise 127.0.0.1:3307. Un autre service du même réseau Compose utilise db:3306 : depuis cet autre conteneur, 127.0.0.1 désignerait ce conteneur lui-même. La publication sur l’adresse de boucle locale limite cet accès d’exercice à la machine hôte.

Le volume nommé db_data conserve le répertoire de données. Les variables suffixées par _FILE indiquent les fichiers contenant les mots de passe. D’après la référence des variables de l’image officielle MariaDB, la création initiale de la base, du compte et des mots de passe concerne un nouveau répertoire de données. Modifier ensuite le fichier de mot de passe ne modifie pas le compte déjà stocké dans un volume initialisé.

Le contrôle healthcheck.sh de l’image officielle vérifie la connexion et l’initialisation d’InnoDB. Un conteneur simplement « running » n’est donc pas encore une preuve que le serveur accepte les requêtes. Le compte app_user créé pour cet exercice possède des droits sur appops_lab permettant notamment d’y créer la table ; un compte applicatif de production doit être ajusté au périmètre réellement nécessaire.

Démarrer le service et enregistrer une ligne

Dans le dossier contenant compose.yaml, exécutez :

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

La première commande vérifie la configuration sans lancer le service. Attendez ensuite que docker compose ps affiche un état de santé healthy pour db. Si l’initialisation échoue, examinez les dernières lignes du journal ; corrigez notamment un fichier secret absent ou le port hôte déjà occupé avant de réessayer. Ne publiez pas des journaux contenant des données sensibles.

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

Saisissez le mot de passe de app-password.txt lorsque le client le demande. Dans ce client MariaDB, exécutez l’exemple SQL complet :

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;

La requête doit renvoyer la ligne d’identifiant 1 et le texte volume survives container replacement, qui signifie que le volume survit au remplacement du conteneur. La création et l’insertion sont prévues pour la première exécution : si la table ou la clé existe déjà, examinez l’exercice existant au lieu de relancer aveuglément son initialisation. Quittez le client avec exit pour revenir au terminal Docker.

Si le client MariaDB est aussi installé sur votre PC, cette autre commande contacte le même serveur via le port publié :

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

Exécutez-y la même requête SELECT note_id, note_text FROM docker_notes; pour confirmer le chemin de connexion. Utiliser le port 3306 à cet endroit pourrait contacter un autre serveur local. Pour une erreur de certificat, configurez les paramètres de confiance appropriés du client au lieu de désactiver systématiquement la vérification TLS.

Remplacer le conteneur en conservant le volume

Fermez d’abord le client SQL, puis exécutez depuis le même dossier de projet :

docker compose down
docker compose up -d

Avec cette configuration, la commande down ordinaire retire les conteneurs et le réseau du projet tout en conservant le volume nommé. Après le redémarrage, attendez de nouveau l’état healthy, reconnectez-vous avec la commande précédente et exécutez SELECT * FROM docker_notes;. La ligne insérée doit être toujours présente : ce contrôle distingue une persistance constatée d’une simple supposition.

docker compose down --volumes supprime aussi les volumes nommés et peut supprimer la base. Ce n’est pas une commande de redémarrage. Ne l’utilisez que pour ce projet d’exercice identifié, après avoir confirmé que ses données peuvent être abandonnées. La référence de Compose down précise la portée de la suppression.

Un volume n’est pas une sauvegarde : sa perte ou son contenu endommagé restent possibles. Pour les données à conserver, appliquez un processus de sauvegarde de base et de contrôle du fichier et vérifiez une restauration distincte. Pour simplement arrêter l’exercice en conservant les données, le down ordinaire ci-dessus suffit dans cette configuration.

Diagnostiquer une connexion avant de réinitialiser les données

Symptôme Vérification utile
Impossible de contacter le moteur Docker Docker Desktop ou Engine est-il démarré ? Quel contexte Docker est sélectionné ?
Port publié occupé Vérifiez le port hôte 3307 et adaptez aussi le port du client PC si vous le changez.
Accès refusé Contrôlez le compte, le mot de passe utilisé lors de l’initialisation et l’existence préalable du volume.
Conteneur actif, mais SQL indisponible Vérifiez la santé du service, les journaux d’initialisation et la différence entre db sur le réseau et 127.0.0.1 sur l’hôte.
Données inattendues après recréation Vérifiez le projet mariadb-appops, le dossier courant, le port de connexion et le volume monté.

La suppression du volume ne doit pas être la première réponse à un échec. Identifiez le serveur et le répertoire de données effectivement utilisés, puis déterminez s’il faut corriger la configuration ou réaliser volontairement une nouvelle initialisation. Changer le mot de passe d’un compte existant est une opération distincte de l’édition d’un fichier utilisé au premier démarrage.