1 21/10/2026 10 min

Installare MariaDB in un container Docker è semplice; farlo in modo sensato lo è meno. La differenza la fanno tre scelte: dove persisti i dati, come gestisci l’inizializzazione del database e con quali limiti fai partire il servizio. Se sbagli uno di questi punti, il container può anche avviarsi, ma al primo restart perdi consistenza, performance o accesso ai dati.

Qui l’obiettivo è un avvio pulito, ripetibile e adatto a un ambiente server. Usiamo un’immagine ufficiale, un volume persistente, una rete dedicata e una configurazione minima ma ragionata. Niente magia: solo i passaggi che servono davvero per avere MariaDB operativo e verificabile.

Scelta dell’immagine e criterio di base

Per un’installazione standard conviene partire dall’immagine ufficiale mariadb. È la strada più lineare per ricevere aggiornamenti coerenti e documentazione allineata al comportamento reale del container. Evita di costruire subito un’immagine custom se non hai un requisito preciso: più strati aggiungi, più difficile diventa capire dove si rompe il bootstrap.

La regola pratica è questa: il container deve essere effimero, i dati no. Quindi il filesystem interno del container non deve essere il punto di persistenza del database. Il dato vero vive in un volume Docker o in una directory bind-mountata sul host. Se il container muore, lo ricrei; se il volume resta, il database resta.

Un’altra scelta iniziale riguarda il nome del servizio e la rete. In ambienti piccoli basta un singolo container esposto su una porta host. In ambienti con più servizi conviene invece usare una rete dedicata, così applicazioni e database si parlano per nome DNS interno, senza esporre MariaDB fuori dal perimetro necessario.

Avvio rapido con Docker run

Se vuoi partire subito, questo è il comando minimo sensato per un’istanza MariaDB persistente e protetta da una password iniziale. Sostituisci i valori con quelli del tuo contesto e non lasciare segreti in chiaro nei comandi della shell oltre il necessario operativo.

docker volume create mariadb_data docker run -d \ --name mariadb01 \ --restart unless-stopped \ -e MARIADB_ROOT_PASSWORD='CambiaQuestaPasswordSubito' \ -e MARIADB_DATABASE=appdb \ -e MARIADB_USER=appuser \ -e MARIADB_PASSWORD='PasswordApplicativaForte' \ -v mariadb_data:/var/lib/mysql \ -p 3306:3306 \ mariadb:11.4

Il volume mariadb_data conserva i file del database. La porta 3306 viene pubblicata sull’host solo se ti serve accesso esterno; se il database deve essere raggiunto soltanto da altri container, puoi omettere -p 3306:3306 e usare solo la rete Docker. In molti casi è la scelta migliore: meno esposizione, meno superficie d’attacco.

Le variabili MARIADB_DATABASE, MARIADB_USER e MARIADB_PASSWORD servono a creare il database applicativo e un utente non amministrativo al primo avvio. Questo è utile soprattutto in contesti dove l’applicazione deve avere privilegi limitati. Il root del database non dovrebbe essere l’account usato dal software web, salvo casi particolari e ben controllati.

Per verificare che il container sia partito davvero, non fermarti allo stato “Up”. Controlla i log iniziali e assicurati che l’inizializzazione non sia rimasta bloccata su password, permessi o directory dati non scrivibile.

docker logs -f mariadb01

Nei log devi vedere il bootstrap del database, la creazione dell’utente e l’avvio del server MariaDB. Se compaiono errori di permission denied sulla directory dati, il problema non è MariaDB in sé: è il mount del volume o i permessi del path sul host.

Persistenza corretta: volume Docker o bind mount

Il volume Docker nominato è la soluzione più pulita per iniziare. Il motore gestisce il percorso fisico, i permessi e la vita del dato senza costringerti a inseguire directory sparse sul filesystem. È anche più semplice da migrare o fare backup, perché il punto di persistenza è ben identificato.

Se invece vuoi usare un bind mount, per esempio per integrare backup esterni o policy di storage già esistenti, la logica resta la stessa: la directory sul host deve essere vuota o coerente con l’istanza che stai avviando, e il processo nel container deve poterla scrivere. Un classico errore è puntare /var/lib/mysql a una directory proprietà di root con permessi incompatibili rispetto all’utente del container.

Un controllo utile sul lato host è questo:

docker inspect mariadb01 --format '{{json .Mounts}}'

Così verifichi dove finisce davvero il dato. Se il mount non è quello atteso, correggi prima di procedere con test funzionali. È molto più facile rimediare subito che scoprire dopo che il container stava scrivendo nel path sbagliato o in un filesystem temporaneo.

Avvio con Docker Compose per un setup ripetibile

Quando il database deve far parte di uno stack più ampio, Compose è quasi sempre la scelta più ordinata. Ti permette di dichiarare rete, volume, variabili d’ambiente e policy di restart in un file versionabile. In produzione è anche il modo migliore per evitare configurazioni “ricordate a memoria”.

services: mariadb: image: mariadb:11.4 container_name: mariadb01 restart: unless-stopped environment: MARIADB_ROOT_PASSWORD: CambiaQuestaPasswordSubito MARIADB_DATABASE: appdb MARIADB_USER: appuser MARIADB_PASSWORD: PasswordApplicativaForte volumes: - mariadb_data:/var/lib/mysql networks: - backend ports: - "3306:3306" volumes: mariadb_data: networks: backend:

Con Compose puoi togliere la pubblicazione della porta se il database non deve essere raggiunto dall’esterno. In quel caso resta accessibile solo ai container sulla stessa rete backend. È una scelta più pulita, soprattutto se hai un reverse proxy o un’applicazione che parla direttamente con il database nel segmento privato.

Dopo il lancio, usa i classici controlli operativi:

docker compose up -d docker compose ps docker compose logs -f mariadb

Il punto da osservare non è solo lo stato del container, ma la sequenza dei log iniziali. Se il database si inizializza correttamente, poi il server entra in ascolto e resta stabile. Se invece riparte in loop, di solito c’è un problema di file system, password non coerente o dati già presenti con schema non compatibile.

Bootstrap iniziale: cosa succede al primo avvio

Il primo avvio di un container MariaDB non è uguale ai successivi. Quando la directory dati è vuota, l’immagine esegue l’inizializzazione del database system, applica le variabili di bootstrap e crea gli utenti richiesti. Al riavvio successivo, invece, il container usa i dati già presenti e salta gran parte della procedura iniziale.

Questo dettaglio conta molto. Se cambi MARIADB_ROOT_PASSWORD dopo che il volume è stato inizializzato, non stai “aggiornando la password del database” in automatico: stai solo modificando la variabile di ambiente per un bootstrap che non verrà più rieseguito. È una delle confusioni più comuni in ambiente container.

Se devi cambiare credenziali già in uso, entra nel container e usa il client MySQL/MariaDB oppure applica la modifica con una procedura di amministrazione esplicita. Non aspettarti che il valore nel file Compose riscriva il contenuto del database esistente.

docker exec -it mariadb01 mariadb -uroot -p

Da lì puoi verificare utenti, privilegi e stato del server. Un controllo basilare è vedere se il database applicativo esiste e se l’utente ha i permessi previsti.

SHOW DATABASES;
SELECT User, Host FROM mysql.user;

Connessione da un’applicazione o da un altro container

Se MariaDB serve un’app web, la soluzione più ordinata è farli stare sulla stessa rete Docker e usare il nome del servizio come host. In Compose, per esempio, l’applicazione può connettersi a mariadb invece di usare un IP fisso o la porta pubblicata sull’host.

Un esempio di connessione lato applicazione potrebbe essere questo: host mariadb, porta 3306, database appdb, utente appuser. L’errore da evitare è puntare a localhost dal container dell’app: dentro un container, localhost è il container stesso, non il database esterno.

Se devi testare la raggiungibilità dalla rete, puoi usare un container temporaneo con client MariaDB. È un modo rapido per distinguere un problema di rete da un problema applicativo.

docker run -it --rm --network backend mariadb:11.4 mariadb -hmariadb -uappuser -p appdb

Se il client si connette, la rete funziona e il problema va cercato altrove: credenziali, permessi, schema o variabili applicative. Se invece fallisce già qui, è probabile che il servizio non sia sulla rete giusta o che il container non stia ascoltando come previsto.

Parametri utili da non lasciare al caso

In un server vero, il container MariaDB non dovrebbe vivere con le sole impostazioni di default. Alcuni parametri meritano attenzione perché incidono su affidabilità e comportamento sotto carico. Non serve esagerare, ma ignorarli del tutto è un errore classico.

Il primo è il fuso orario, se l’applicazione o i log devono allinearsi a un’area geografica specifica. Il secondo è la dimensione della memoria assegnata al container, perché un database che compete senza limiti con altri servizi può finire in pressione OOM. Il terzo è il logging, che deve restare disponibile anche quando il servizio degrada.

Se vuoi ridurre il rischio di consumo eccessivo di risorse, puoi limitare memoria e CPU a livello Docker. È una misura prudente, soprattutto su host condivisi.

docker run -d \ --name mariadb01 \ --restart unless-stopped \ --memory=1g \ --cpus=1.0 \ -e MARIADB_ROOT_PASSWORD='CambiaQuestaPasswordSubito' \ -v mariadb_data:/var/lib/mysql \ mariadb:11.4

Non è una garanzia di stabilità, ma è un modo concreto per evitare che MariaDB saturi l’host in caso di query pesanti o configurazioni errate. La metrica da osservare, in questo caso, è l’uso di memoria del container e l’eventuale presenza di OOM kill nei log di sistema.

Backup e ripristino: cosa fare prima che serva davvero

Il backup non è un tema separato dal deployment: va pensato subito. Con i container è facile illudersi che un volume sia già “protetto” perché è persistente. Persistente non significa salvato. Se il disco si corrompe o cancelli il volume per errore, il dato è perso come su qualsiasi altro server.

Per un controllo rapido, definisci almeno una procedura di dump logico. È meno elegante di una replica o di snapshot storage, ma è chiara e verificabile. Il comando base è questo:

docker exec mariadb01 mariadb-dump -uroot -p --all-databases > backup.sql

Se il database è grande o l’RPO è stretto, il dump logico potrebbe non bastare da solo. In quel caso devi integrare con snapshot del volume, replica o backup fisico coerente. Ma per un’istanza piccola o per ambienti di test, un dump pianificato e verificato è già molto meglio di niente.

Per il ripristino, la prova vera non è avere il file .sql, ma saperlo reimportare in un container pulito. Senza un test di restore, il backup resta una supposizione. Questo vale sempre, e con i database vale doppio.

Problemi tipici e come riconoscerli in fretta

Se il container esce subito o continua a riavviarsi, il primo sospetto è il mount dati. Controlla i log e cerca errori relativi a permission denied, directory non inizializzabile o data directory già occupata da file incompatibili. La verifica più utile resta sempre il log iniziale del container.

Se l’applicazione non si connette, verifica tre cose in ordine: host corretto, porta corretta, credenziali corrette. In ambiente Docker, il problema più frequente è usare l’indirizzo sbagliato, ad esempio localhost al posto del nome del servizio. La seconda causa comune è la porta esposta sull’host ma non necessaria o non raggiungibile dal segmento di rete atteso.

Se il database parte ma poi degrada sotto carico, guarda CPU, memoria e I/O del volume. Un database containerizzato non ha bisogno di privilegi speciali, ma ha bisogno di storage decente. Se il disco è lento, l’esperienza complessiva peggiora subito, anche con query banali.

Quando la configurazione funziona in test ma non in produzione, la differenza di solito sta nei dati, non nel container. In produzione ci sono più connessioni, più persistenza, più probabilità di ereditare un volume sporco o un set di variabili incoerenti. Per questo conviene tenere il file Compose sotto controllo versione e documentare ogni modifica rilevante.

Una configurazione minimale ma solida

Se devo riassumere una base sana per MariaDB in Docker, la formula è questa: immagine ufficiale, volume persistente, rete dedicata, password robuste, accesso limitato e log sempre consultabili. Non serve di più per il 90% dei casi iniziali; serve piuttosto non sbagliare questi elementi.

Il container è solo il mezzo. La parte importante è il contratto operativo che costruisci attorno: dove scrive, chi lo raggiunge, come si riavvia, come lo salvi e come verifichi che sia davvero integro. Se questi punti sono chiari, MariaDB in Docker diventa un servizio prevedibile invece di un oggetto fragile da toccare il meno possibile.