Guida a Docker per i docenti: ambienti di test isolati e uniformi

DIDATTICA · Area Docenti • Docker per docenti

✍ Autore: profgiagnotti | Ambienti uniformi per tutta la classe

Guida a Docker per i docenti: ambienti di test isolati e uniformi

Come distribuire alla classe un unico file docker-compose.yml per far lavorare tutti sulla stessa identica versione di database, server o interprete, e dire addio al «sul mio PC funzionava».

🐳 Docker📦 Compose👩‍🏫 Classe uniforme

📚 Indice

1. Il problema che Docker risolve 2. Quattro parole da conoscere 3. Prerequisiti e installazione 4. Anatomia di un docker-compose.yml 5. Kit pronto all'uso: quattro ambienti da copiare e incollare 6. I comandi che gli studenti devono conoscere 7. Versioni bloccate, dati e configurazione 8. Distribuirlo alla classe con GitHub 9. Sicurezza e buone pratiche 10. Problemi frequenti 11. Kit pronto all'uso (scaricabile) 12. Checklist finale

1. Il problema che Docker risolve

In una classe ci sono Windows, macOS, Linux, versioni diverse di Python, un MySQL installato a metà e un PC di classe con la porta 3306 già occupata. Il risultato: metà lezione si perde in installazioni e problemi che non c'entrano con la materia.

Con Docker il docente descrive l'ambiente una volta sola, in un file di testo. Gli studenti lo avviano con un solo comando e ottengono tutti lo stesso ambiente, identico al tuo e identico a quello che userai per correggere.

CONCETTO CHIAVE

File docker-compose.yml  →  docker compose up  →  stesso database, stesso server, stesso interprete
(nel repository)          (su ogni PC)         per tutti gli studenti

💡 Nota

Colleghi, da ricordare bene: con Docker finite le scuse “sul mio PC funzionava”. Tutti hanno stesso PHP, stesso MySQL, stessa versione. Non fate questo errore: far installare MySQL a mano a 25 PC diversi il primo giorno di laboratorio.

2. Quattro parole da conoscere

Termine	Cosa significa, in parole semplici
Immagine	Il «modello» di un ambiente già pronto (ad esempio mysql:8.4 o python:3.12-slim). Non cambia mai.
Container	Un'istanza in esecuzione di un'immagine: una piccola macchina isolata, creata e distrutta in pochi secondi.
Volume	Uno spazio su disco che sopravvive al container, per non perdere i dati del database.
Compose	Lo strumento che avvia più container insieme (ad esempio sito web + database) leggendo un unico file YAML.

📌 Differenza dalle macchine virtuali

Un container non contiene un intero sistema operativo, quindi è più leggero e parte in pochi secondi.

3. Prerequisiti e installazione

Windows e macOS: Docker Desktop. Su Windows richiede WSL 2 (viene proposto dall'installazione) e permessi di amministratore.
Linux: Docker Engine con il plugin Compose, dal gestore pacchetti della distribuzione.
Alternative: Podman, Rancher Desktop, Colima, se Docker Desktop non è adatto. Verifica le condizioni di licenza di Docker Desktop per l'uso didattico sul sito ufficiale.
Se i PC dei laboratori non permettono installazioni: usa GitHub Codespaces (vedi sezione 8): Docker gira nel cloud e lo studente lavora dal browser.

Per verificare l'installazione:

VERIFICA INSTALLAZIONE

docker --version
docker compose version

Nei comandi di questa guida si usa docker compose (con lo spazio), la versione attuale. Il vecchio docker-compose (con il trattino) è superato.

4. Anatomia di un docker-compose.yml

ESEMPIO POSTGRES

services:                 # l'elenco dei container
  db:                      # nome scelto da noi
    image: postgres:16     # quale immagine, CON versione fissata
    environment:           # variabili di configurazione
      POSTGRES_PASSWORD: studente
    ports:
      - "5432:5432"        # porta-PC : porta-container
    volumes:
      - pgdata:/var/lib/postgresql/data   # dati permanenti

volumes:
  pgdata:                  # dichiarazione del volume

Punti chiave da spiegare agli studenti:

Versione fissata: postgres:16 e non postgres:latest. È la riga che garantisce che tutti abbiano la stessa versione.
Porte: a sinistra la porta sul PC dello studente, a destra quella nel container.
Nomi dei servizi: all'interno della rete di Compose i container si trovano per nome. Il sito web si collega al database scrivendo host=db, non localhost.
Indentazione: solo spazi, due per livello, mai tabulazioni.

5. Kit pronto all'uso: quattro ambienti da copiare e incollare

Ogni ambiente è una cartella autonoma. Gli stessi file sono nel Kit scaricabile (sezione 11).

5.1 Python con PyTest

Servizio principale: esegue main.py. Servizio test: lancia PyTest solo quando viene richiesto.

docker-compose.yml

PYTHON + PYTEST - COMPOSE

services:
  python:
    build: .
    working_dir: /app
    volumes:
      - ./:/app
    command: python main.py

  test:
    build: .
    working_dir: /app
    volumes:
      - ./:/app
    command: python -m pytest -v
    profiles: ["test"]

Dockerfile

DOCKERFILE

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

requirements.txt contiene almeno pytest.

Uso:

USO PYTHON

docker compose run --rm python   # esegue main.py
docker compose run --rm test     # esegue i test

5.2 Sito PHP + MySQL + phpMyAdmin

L'ambiente classico per web e database: un server Apache con PHP, MySQL e un'interfaccia grafica per vedere le tabelle.

docker-compose.yml

PHP + MYSQL + PHPMYADMIN

services:
  web:
    build: .
    ports:
      - "8080:80"
    volumes:
      - ./www:/var/www/html
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: scuola
      MYSQL_USER: studente
      MYSQL_PASSWORD: studente
    volumes:
      - db_data:/var/lib/mysql
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -uroot -p$MYSQL_ROOT_PASSWORD"]
      interval: 5s
      timeout: 5s
      retries: 20

  phpmyadmin:
    image: phpmyadmin:5
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db
    depends_on:
      - db

volumes:
  db_data:

Dockerfile (aggiunge a PHP il supporto per MySQL)

DOCKERFILE PHP

FROM php:8.3-apache
RUN docker-php-ext-install pdo pdo_mysql mysqli

Indirizzi dopo l'avvio:

sito: http://localhost:8080
phpMyAdmin: http://localhost:8081 (utente studente, password studente)

Cosa fa init.sql: crea tabelle e dati iniziali la prima volta che il database parte. È il modo migliore per consegnare a tutti la stessa base di dati.

5.3 PostgreSQL + Adminer

POSTGRES + ADMINER

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: studente
      POSTGRES_PASSWORD: studente
      POSTGRES_DB: scuola
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U studente -d scuola"]
      interval: 5s
      timeout: 5s
      retries: 20

  adminer:
    image: adminer:4
    ports:
      - "8082:8080"
    depends_on:
      - db

volumes:
  pgdata:

Adminer è raggiungibile su http://localhost:8082 (sistema: PostgreSQL, server: db, utente e password studente).

5.4 Node.js

NODE.JS

services:
  node:
    image: node:20-slim
    working_dir: /app
    volumes:
      - ./:/app
    command: sh -c "npm install && node index.js"

  test:
    image: node:20-slim
    working_dir: /app
    volumes:
      - ./:/app
    command: sh -c "npm install && npm test"
    profiles: ["test"]

USO NODE

docker compose run --rm node
docker compose run --rm test

6. I comandi che gli studenti devono conoscere

Stampa questa tabella e consegnala alla classe.

Comando	Cosa fa
docker compose up -d	Avvia tutti i servizi in background
docker compose up -d --build	Avvia ricostruendo le immagini (dopo aver cambiato il Dockerfile)
docker compose ps	Mostra cosa è in esecuzione
docker compose logs -f db	Segue i messaggi del servizio db
docker compose run --rm test	Esegue una sola volta il servizio test
docker compose exec db bash	Apre una shell dentro il container db
docker compose down	Ferma e rimuove i container, conserva i dati
docker compose down -v	Ferma tutto e cancella anche i dati (ripartenza da zero)

💡 Nota

Colleghi, regola d'oro da ripetere: down per spegnere, down -v per ricominciare da capo. Il database viene ricreato da init.sql solo se il volume è vuoto. Non fate questo errore: dire agli studenti di cancellare cartelle a mano.

7. Versioni bloccate, dati e configurazione

7.1 Bloccare le versioni

Scrivi sempre il numero di versione (mysql:8.4, python:3.12-slim, node:20-slim).
Evita latest: oggi è una versione, tra sei mesi un'altra.
A inizio anno scolastico aggiorna le versioni, provale e ripubblica il modello.

7.2 Dati persistenti e reset

I volumi conservano il database tra un avvio e l'altro.
Per consegnare dati iniziali identici a tutti usa init.sql nella cartella docker-entrypoint-initdb.d.
Se modifichi init.sql dopo il primo avvio, gli studenti devono eseguire docker compose down -v per rigenerare il database.

7.3 Password e file .env

Per uso didattico password semplici vanno bene, ma conviene metterle in un file .env nella stessa cartella:

.ENV

DB_PASSWORD=studente

e leggerle nel compose con:

ENV IN COMPOSE

environment:
  MYSQL_PASSWORD: ${DB_PASSWORD}

Il file .env si trova automaticamente da Compose. Non usare mai password reali e non inserire in un repository condiviso chiavi di servizi esterni.

8. Distribuirlo alla classe con GitHub

Il modo più semplice: mettere il file docker-compose.yml nel repository modello di GitHub Classroom (vedi la guida precedente). Ogni studente lo riceve insieme alla consegna.

Flusso consigliato:

Il repository modello contiene docker-compose.yml, Dockerfile, init.sql e il codice di partenza.
Lo studente clona il repository e lancia docker compose up -d.
Lavora sul codice nel suo editor: la cartella del progetto è condivisa con i container grazie ai volumi.
A ogni git push le GitHub Actions (guida precedente) eseguono i test, e per farlo possono usare lo stesso docker compose, così l'ambiente dei test coincide con quello di sviluppo.

8.1 Workflow Actions che usa Docker Compose

WORKFLOW TEST CON DOCKER

name: Test con Docker

on:
  push:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Esegui i test nell'ambiente Docker
        run: docker compose run --rm test

8.2 Se in laboratorio non si può installare Docker: Codespaces e Dev Containers

Aggiungendo al repository il file .devcontainer/devcontainer.json, lo studente può aprire il progetto in GitHub Codespaces (o in VS Code con l'estensione Dev Containers) e ritrovarsi già dentro l'ambiente corretto, senza installare nulla in locale.

DEVCONTAINER.JSON

{
  "name": "Ambiente del corso",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "python",
  "workspaceFolder": "/app"
}

Verifica i limiti di utilizzo gratuito di Codespaces per l'istruzione nelle condizioni attuali di GitHub.

9. Sicurezza e buone pratiche

Le porte pubblicate sono visibili anche in rete: per i servizi che non devono esserlo scrivi 127.0.0.1:5432:5432, così il database è raggiungibile solo dal PC dello studente.
Il container non è una cassaforte: non eseguire codice di cui non ti fidi con permessi elevati e non montare cartelle sensibili del PC.
Immagini ufficiali: usa quelle «Docker Official Image» o dei progetti ufficiali; evita immagini sconosciute.
Un compito, una cartella: tenere ogni ambiente separato evita conflitti tra porte e volumi.
Spazio su disco: le immagini occupano diversi GB. Ricorda a fine corso docker system prune (con cautela: rimuove oggetti inutilizzati).

10. Problemi frequenti

Sintomo	Causa probabile	Soluzione
port is already allocated	La porta è già usata (es. MySQL già installato sul PC)	Cambia la porta a sinistra, ad esempio "3307:3306"
Cannot connect to the Docker daemon	Docker Desktop non è avviato	Avvia Docker Desktop e attendi che sia pronto
Il sito non si collega al database	Si usa localhost invece del nome del servizio	Usa db come host
Il database non si aggiorna dopo aver modificato init.sql	Il volume contiene ancora i vecchi dati	docker compose down -v, poi up -d
permission denied su Linux	L'utente non fa parte del gruppo docker	Aggiungi l'utente al gruppo e riavvia la sessione
Errore di YAML all'avvio	Indentazione con tabulazioni e livelli sbagliati	Usa solo spazi, due per livello
Su Windows i file non si aggiornano nel container	Progetto su un disco o percorso non condiviso con Docker	Tieni il progetto nella cartella utente, oppure nel filesystem di WSL oppure nel volume nominato
Più lento del previsto su macOS o Windows	Le cartelle condivise hanno un costo in prestazioni	Per progetti grandi usa Codespaces o i volumi nominati

11. Kit pronto all'uso (scaricabile)

Il kit allegato contiene:

01-python-pytest/: Dockerfile, compose, main.py e un test di esempio;
02-php-mysql-phpmyadmin/: compose, Dockerfile, init.sql e una pagina index.php che prova la connessione al database;
03-postgres-adminer/: compose e init.sql;
04-node/: compose, index.js e un test di esempio;
devcontainer-esempio/: il file per Codespaces e Dev Containers;
workflow-actions/docker-test.yml: il workflow GitHub Actions della sezione 8.1;
LEGGIMI.md: istruzioni e comandi.

Come usarlo in 5 passi:

Scegli la cartella dell'ambiente che ti serve e copiala nel tuo repository modello.
Adatta password, nomi e init.sql alla tua materia.
Prova tutto sul tuo PC: docker compose up -d.
Verifica da zero con docker compose down -v e poi un nuovo up -d, per simulare uno studente al primo avvio.
Pubblica il modello su GitHub Classroom e distribuisci la sezione 6 di questa guida come promemoria.

12. Checklist finale

CHECKLIST FINALE

☐ Tutte le immagini hanno una versione fissata (niente latest)
☐ L'ambiente parte con un solo comando su un PC pulito
☐ init.sql crea tabelle e dati iniziali
☐ Le porte non entrano in conflitto con altri servizi comuni
☐ Le password sono didattiche e non reali
☐ Hai provato il ciclo down -v + up -d
☐ Gli studenti hanno il promemoria dei comandi
☐ Hai un piano B per i PC dove non si può installare Docker (Codespaces)

🧰 Adesso prova a realizzare ciò che hai letto con il kit che ho preparato per te

Ho preparato un kit scaricabile con i 4 ambienti Docker completi, Dockerfile, init.sql, devcontainer e workflow Actions. Scaricalo e provalo subito con la tua classe.

⬇️ Scarica il Kit Docker per Docenti

ZIP con python-pytest, php-mysql-phpmyadmin, postgres-adminer, node, devcontainer e workflow.

🏫 Hub Area Docenti

Torna all'hub con tutte le guide tecniche e normativa per docenti.

← Area Docenti HUB

📚 Il tuo prossimo passo ora

Prendi l'ambiente del kit che ti serve (consiglio: inizia con 01-python-pytest), copialo in un repo di prova, lancia docker compose up -d e poi down -v. Se parte al primo colpo su PC pulito, è pronto per la tua classe. Se vuoi, scrivi nei commenti che materia insegni: ti suggerisco quale ambiente usare.