Corso MariaDB / Creare un ambiente di esercitazione con Docker Compose

Docker Compose può definire in un solo file un container MariaDB, la porta di connessione e lo spazio persistente. Consente di preparare un ambiente di studio separato senza installare direttamente un servizio MariaDB sul computer. Eliminare il container ed eliminare il volume dei dati hanno conseguenze diverse.

Definire il laboratorio e verificarne i prerequisiti

Docker esegue un'applicazione in un container; Compose ne descrive le impostazioni in YAML, un formato testuale per dati strutturati. L'esercizio espone il database su 127.0.0.1:3307. Una porta host separata consente di affiancarlo a un server sulla 3306. La guida alla diagnosi delle connessioni distingue i percorsi; la guida al backup del database descrive le copie da mantenere fuori dal volume.

Installare Docker Engine con plugin Compose oppure Docker Desktop seguendo le istruzioni ufficiali di installazione di Compose. Su Windows usare container Linux. Avviare il motore Docker e verificare entrambi i comandi del terminale prima di preparare il database:

docker version
docker compose version

La configurazione sceglie esplicitamente la famiglia di immagini mariadb:11.8. Il tag può riferirsi a patch successive. Per una riproduzione esatta registrare il tag di patch o il digest approvato, identificatore del contenuto dell'immagine. Controllare YAML e SQL non sostituisce la verifica di avvio, healthcheck e persistenza del volume nell'ambiente Docker.

Preparare progetto e file delle password

  1. Creare una nuova cartella mariadb-appops e aprirvi il terminale. Non eseguire i comandi da un altro progetto Compose.
  2. Creare la sottocartella secrets con root-password.txt e app-password.txt. Salvare una password di prova diversa in ogni file UTF-8, senza frasi esplicative. Non lasciare file vuoti.
  3. Salvare la configurazione completa seguente come compose.yaml. Creare anche .gitignore con le due righe sotto per escludere le password dal controllo versione, poi limitare l'accesso ai file.
secrets/
.env

Compose secrets fornisce i file soltanto ai servizi indicati. Non trasforma i file locali sorgenti in una cassaforte cifrata di password. Proteggere file e accesso a Docker. La documentazione ufficiale di Compose secrets descrive il montaggio dei file e il requisito dei container Linux.

Comprendere la configurazione Compose completa

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:

Il computer espone la porta 3307, mentre MariaDB nel container usa 3306. Un client sull'host si collega a 127.0.0.1:3307; un altro servizio sulla stessa rete Compose usa db:3306. L'associazione all'indirizzo di loopback limita questa porta pubblicata al percorso locale dell'host.

Il volume denominato db_data conserva la directory dei dati. Le variabili con suffisso _FILE indicano i file delle password. Il riferimento ufficiale delle variabili dell'immagine MariaDB spiega la creazione di database e account quando la directory dei dati è nuova. Modificare il file della password non cambia automaticamente l'account già presente in un volume inizializzato.

Lo script ufficiale healthcheck.sh controlla connessione e inizializzazione InnoDB. Un container in esecuzione non dimostra ancora che il database sia pronto per le query.

Avviare il servizio e verificare una riga memorizzata

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

Il primo comando verifica la configurazione tramite Compose. Accertarsi poi che il servizio raggiunga healthy; altrimenti esaminare i log di inizializzazione. Correggere secret mancanti o una porta host occupata prima di riprovare. Esaminare i log per informazioni sensibili prima di condividerli.

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

Inserire al prompt la password di app-password.txt. Eseguire nel client l'SQL completo seguente: il risultato è una riga. La creazione della tabella è prevista per la prima esecuzione; se esiste già, controllare lo stato conservato prima di ripetere la preparazione.

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;

Il testo inglese memorizzato significa «il volume sopravvive alla sostituzione del container» ed è conservato come dato dimostrativo. Ritrovare la stessa riga dopo la sostituzione sarà il controllo della persistenza.

Se mariadb è disponibile sul computer host, il comando seguente raggiunge lo stesso server tramite la porta pubblicata. Usare 3306 su questo percorso potrebbe collegare a un altro server locale:

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

Sostituire il container conservando il volume

docker compose down
docker compose up -d

In questa configurazione, down senza opzioni aggiuntive rimuove container e rete del progetto e conserva il volume dati denominato. Quando il servizio sostitutivo è healthy, ricollegarsi ed eseguire SELECT * FROM docker_notes;. La riga inserita deve essere ancora presente. Rileggerla verifica i dati conservati, anziché presumerne la persistenza.

docker compose down --volumes rimuove anche i volumi e può eliminare il database. Usarlo soltanto dopo aver accertato che i dati di questo progetto siano eliminabili. Non è il comando ordinario per riavviare il server. I dati da conservare richiedono comunque un backup separato del database. Il riferimento ufficiale di Compose down descrive gli oggetti rimossi.

Diagnosticare gli errori prima di inizializzare nuovamente i dati

Sintomo Controllo
Motore Docker irraggiungibile Docker Desktop o Engine avviato e contesto Docker corretto
Porta pubblicata occupata Porta host 3307; adeguare il client se cambia
Access denied Account e password usati all'inizializzazione e volume già esistente
Container avviato ma SQL non disponibile Healthcheck, log e distinzione tra db nella rete e 127.0.0.1 sull'host
Dati inattesi dopo la ricreazione Progetto mariadb-appops, cartella di lavoro, porta e volume montato

Non usare la cancellazione del volume come prima diagnosi. Individuare server e directory dei dati effettivi e stabilire se il problema richieda una correzione delle impostazioni o una nuova inizializzazione intenzionale.