Docker init: come inizializzare un progetto con Docker (guida passo passo)

Per qualche motivo, configurare un nuovo progetto con Docker richiede sempre più tempo del dovuto.

Cerchi un template su Google, lo incolli, cambi un paio di righe e speri per il meglio. La build fallisce, quindi fai qualche ritocco e ripeti il ciclo finché non funziona. Ogni nuovo progetto inizia allo stesso modo: con un file vuoto e un vago ricordo di cosa aveva funzionato l’ultima volta. È chiaramente un problema di setup, e non è colpa di Docker.

La buona notizia è che docker init risolve questo problema. È un comando CLI che rileva il tipo di progetto e genera un Dockerfile, un .dockerignore e un file Compose.

In questo articolo ti mostro come funziona docker init, come usarlo passo passo con un vero progetto Python e quando è lo strumento giusto per il lavoro.

Se sei alle prime armi con Docker e la containerizzazione, scopri perché è una parte essenziale del toolkit di chi lavora con i dati iscrivendoti al nostro corso Introduction to Docker.

Cos’è Docker init

docker init è uno strumento da riga di comando che configura Docker per il tuo progetto. Genera i file necessari per containerizzare la tua app. Quindi non servono template né copia-incolla.

Produce tre file:

• Dockerfile - definisce come viene costruita l’immagine del container
• .dockerignore - indica a Docker quali file escludere dal contesto di build
• compose.yml - opzionale, ma utile per setup multi-servizio

La parte intelligente è il rilevamento automatico del progetto. docker init guarda la struttura e capisce quale stack stai usando - Python, Node.js, Go e altri. Poi genera file in base a quello stack, invece di usare un template generico.

Non è uno strumento di deployment e non gestisce i container in produzione. Si limita ad avviare la configurazione così puoi concentrarti sul lavoro vero.

Come funziona Docker init

docker init segue sempre un flusso in quattro step ogni volta che lo esegui.

Per prima cosa esegui docker init nella cartella del progetto. Docker scansiona la directory, rileva il tipo di progetto e sceglie il template di configurazione corretto. Poi ti guida con una breve serie di prompt interattivi - ad esempio su quale porta gira l’app e quale comando la avvia. Dopo le risposte, genera i file.

Il tutto richiede meno di un minuto.

I prompt sono semplici e raramente richiedono spiegazioni aggiuntive. Puoi accettare i valori predefiniti premendo Invio o inserire i tuoi se non vanno bene. 

Ecco cosa vedrai alla prima esecuzione del comando:

Schermata di configurazione di Docker init

Ti mostro subito questo processo più nel dettaglio.

Come usare Docker init passo passo

Ecco una panoramica su come passare da una cartella di progetto a un container in esecuzione.

Passo 1: vai nella directory del progetto

Apri il terminale e vai alla root del progetto, la cartella che contiene il codice dell’applicazione.

cd /path/to/your/project

docker init genera i file in base alla directory in cui lo esegui, quindi assicurati di essere nella cartella giusta prima di procedere.

Passo 2: esegui Docker init

Esegui il seguente comando:

docker init

Docker analizzerà la cartella del progetto, rileverà lo stack e avvierà il prompt di configurazione interattivo.

Passo 3: rispondi ai prompt

docker init ti farà un paio di domande:

• Piattaforma dell’applicazione - il linguaggio o framework che il tuo progetto usa (Python, Node.js, Go, ecc.)
• Porta - la porta su cui l’app è in ascolto
• Comando di avvio - il comando che Docker deve eseguire per avviare l’app

Puoi accettare i valori suggeriti premendo Invio o inserire i tuoi. Se docker init rileva il tuo stack, i default sono di solito sufficienti per iniziare.

Passo 4: rivedi i file generati

Dopo aver risposto ai prompt, docker init scrive tre file nella cartella del progetto:

.
├── Dockerfile
├── .dockerignore
└── compose.yaml

Apri ogni file e leggilo. I file generati includono commenti che spiegano cosa fa ogni riga, quindi vale la pena spendere qualche minuto per capire cosa è stato creato prima di fare una build.

Passo 5: build e avvio del container

Crea e avvia il container con Docker Compose:

docker compose up --build

Il flag --build indica a Docker di costruire l’immagine dal tuo Dockerfile prima di avviare il container. Una volta in esecuzione, la tua app dovrebbe essere accessibile sulla porta specificata al passo 3.

Tipi di progetto supportati in Docker init

docker init supporta nativamente gli stack applicativi più comuni. Eccone alcuni:

• Python
• Node.js
• Go
• Java
• .NET

Rileva lo stack automaticamente. Quando esegui docker init, scansiona la cartella del progetto alla ricerca di file specifici del linguaggio - come requirements.txt per Python o package.json per Node.js - e sceglie il template giusto in base a ciò che trova.

Ogni template è adattato allo stack. Un progetto Python ottiene una base image, comandi di installazione e comando di avvio diversi rispetto a un progetto Go. Non stai ricevendo un Dockerfile unico con una variabile di linguaggio scambiata. Cambia proprio la struttura in base a ciò che stai costruendo.

Se docker init non riesce a rilevare lo stack, ti chiederà di sceglierne uno manualmente dall’elenco.

File generati da Docker init

docker init genera tre file, ognuno con un ruolo diverso nella tua configurazione.

Dockerfile

Il Dockerfile definisce come Docker costruisce l’immagine del container. Dice a Docker quale base image usare, come installare le dipendenze e quale comando eseguire all’avvio del container.

Ecco un esempio di Dockerfile Python generato:

FROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Ti conviene rivedere questo file prima di fare la build. L’output generato è un buon punto di partenza, ma potresti doverlo modificare - ad esempio per aggiungere variabili d’ambiente o regolare la versione della base image.

.dockerignore

Il file .dockerignore indica a Docker quali file escludere dal contesto di build. È l’insieme di file che Docker invia al motore di build quando crea l’immagine.

Senza di esso, Docker copierebbe tutto nella cartella del progetto dentro l’immagine, inclusi .git, node_modules o file di configurazione locali che non servono in produzione. Questo aumenta la dimensione dell’immagine e può esporre file che non volevi includere.

Un tipico .dockerignore è così:

.git
.env
__pycache__
*.pyc
node_modules

File Docker Compose

Il file compose.yaml serve per eseguire setup multi-container. Definisce servizi, porte, volumi e come i container si connettono tra loro.

Per un’app semplice a singolo container potresti non averne bisogno. Ma se il tuo progetto include un database, una cache o altri servizi accanto all’app, il file Compose è il punto unico in cui configurare tutto.

Esempio: usare Docker init con un progetto Python

Eseguiamo docker init su un progetto reale. Userò una FastAPI minimale con una singola route come esempio.

Ecco la struttura del progetto prima di eseguire docker init:

my-fastapi-app/
├── app.py
└── requirements.txt

app.py ha una singola route Hello World:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

E requirements.txt contiene queste due dipendenze:

fastapi
uvicorn

Esecuzione di docker init

Per iniziare, vai nella cartella del progetto ed esegui:

docker init

Progetto rilevato da Docker init

docker init rileva Python da requirements.txt e ti fa un paio di domande. Ecco come appaiono i prompt e cosa rispondere:

Prompt di Docker init per un progetto Python

Cosa viene generato

Dopo aver risposto ai prompt, la cartella del progetto appare così:

Nuova struttura della cartella del progetto

Ci sono tre nuovi file. Vediamoli uno per uno.

Il Dockerfile

# syntax=docker/dockerfile:1

ARG PYTHON_VERSION=3.14
FROM python:${PYTHON_VERSION}-slim as base

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

USER appuser

COPY . .

EXPOSE 8000

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Qui spiccano alcune cose. PYTHONDONTWRITEBYTECODE=1 impedisce a Python di scrivere file .pyc su disco e PYTHONUNBUFFERED=1 garantisce che i log compaiano in tempo reale invece di restare in buffer: entrambi sono ottimi default per app containerizzate.

Il blocco adduser crea un utente non privilegiato chiamato appuser per eseguire l’applicazione. Per impostazione predefinita, i container Docker girano come root, il che è un rischio di sicurezza. Eseguire come utente non root limita ciò che un attaccante può fare se riesce a evadere la tua app.

Il flag --mount=type=cache nello step di pip install dice a Docker di mettere in cache i pacchetti scaricati tra le build. Significa che le build successive non riscaricheranno le dipendenze da zero, velocizzando il tutto.

Il .dockerignore

**/.DS_Store
**/__pycache__
**/.venv
**/.env
**/.git
**/.gitignore
**/node_modules
**/Dockerfile*
**/compose.y*ml
README.md

Il file .dockerignore esclude file che non appartengono alla tua immagine. File di ambiente locali come .env, cartelle di versionamento come .git e file cache di Python come __pycache__ vengono saltati. Anche il Dockerfile e il compose.yaml sono esclusi: Docker non ha bisogno di questi file all’interno dell’immagine che sta costruendo.

Il compose.yaml

services:
  server:
    build:
      context: .
    ports:
      - 8000:8000

Il file Compose definisce la tua app come un servizio chiamato server, lo builda dal Dockerfile nella directory corrente e mappa la porta 8000 dell’host sulla porta 8000 del container.

Tutti e tre i file generati includono alcuni commenti che ho omesso per mantenere tutto pulito.

Esegui docker compose up --build e la tua app FastAPI sarà disponibile su http://localhost:8000.

App FastAPI in esecuzione in un container

Docker init vs setup manuale del Dockerfile

Entrambi gli approcci portano a un Dockerfile funzionante, quindi dipende da quanto controllo ti serve e da quanto in fretta vuoi arrivarci.

Docker init

docker init è l’opzione più rapida. Rispondi a pochi prompt e ottieni una configurazione funzionante e ragionevolmente sicura in meno di un minuto. I file generati seguono le best practice di Docker - utente non root, caching della build, pattern .dockerignore adeguati - quindi non parti da zero.

È ideale quando inizi un nuovo progetto, stai facendo onboarding a un collega o vuoi solo una base solida su cui costruire senza perdere tempo con il boilerplate.

Ma resta il tema della flessibilità. I template coprono bene i casi comuni, ma sono pur sempre template. Se il tuo progetto ha una struttura insolita o requisiti di build specifici, incontrerai i limiti di ciò che docker init può generare.

Setup manuale

Scrivere il tuo Dockerfile a mano ti dà il pieno controllo su ogni layer, istruzione e decisione di build. Puoi implementare multi-stage build per minimizzare la dimensione dell’immagine, usare base image personalizzate o affinare il comportamento della cache in modi che docker init non può prevedere.

Però devi sapere quello che fai. Un Dockerfile scritto male può produrre immagini troppo grandi, introdurre problemi di sicurezza o fallire in modi difficili da debuggare, soprattutto se non hai molta esperienza.

Quale usare

Ecco un modo semplice di pensarci:

Confronto tra Docker init e setup manuale

Un buon approccio è iniziare con docker init e poi modificare manualmente i file generati man mano che crescono i requisiti.

Quando usare Docker init

docker init non è lo strumento giusto per ogni situazione. Ecco quando ha senso e quando no.

Scegli docker init quando:

• Stai iniziando un nuovo progetto: avvia la configurazione Docker in meno di un minuto, così puoi concentrarti sul codice invece che sul setup della containerizzazione

• Stai imparando Docker: i file generati sono ben commentati e seguono le best practice. Sono un punto di partenza migliore di uno snippet casuale trovato su Stack Overflow

• Stai prototipando: quando ti serve un ambiente containerizzato al volo e non ti interessa ottimizzare la build, docker init ti fornisce qualcosa che funziona

• Stai standardizzando in un team: invece che ogni sviluppatore si scriva il proprio Dockerfile, docker init dà a tutti un punto di partenza coerente con la stessa struttura e gli stessi default

Detto questo, evita docker init quando:

• Ti servono multi-stage build: se stai ottimizzando la dimensione dell’immagine separando la build in più fasi - compilazione in una, esecuzione in un’altra - dovrai scriverlo a mano. Il Dockerfile generato è a singolo stage

• Hai requisiti di produzione complessi: base image personalizzate, strategie di caching avanzate, layout di progetto non standard - non sono cose che docker init può prevedere. Finirai per perdere più tempo ad aggirare i file generati che a scriverti i tuoi

In sintesi, docker init è un punto di partenza. Usalo per metterti in moto, poi modifica i file generati man mano che crescono le esigenze.

Limitazioni di Docker init

Man mano che il progetto cresce, puoi incontrare alcune limitazioni. Eccone alcune.

I file generati sono basati su template. Sono pensati per coprire i casi più comuni per ogni stack supportato, quindi funzionano bene per progetti standard e meno bene per tutto ciò che è fuori da quel perimetro. Se il tuo progetto ha una struttura insolita, è possibile che i file generati non la considerino.

Un’altra limitazione frequente è che quasi sempre serve una messa a punto manuale. I default sono buoni, ma restano default. Probabilmente dovrai regolare la versione della base image, modificare variabili d’ambiente o adattare il comando di avvio prima che la configurazione calzi a pennello. Considera i file generati come una prima bozza, niente di più.

docker init non supporta nemmeno pattern di build avanzati. Multi-stage build, argomenti di build personalizzati, logica condizionale e altre tecniche usate dagli utenti esperti per immagini di produzione sono fuori dallo scopo dello strumento. Ma se ti servono queste cose, probabilmente ti scrivi il Dockerfile da solo comunque.

Niente di tutto questo rende docker init uno strumento scarso. Significa solo che devi avere le giuste aspettative: elimina il problema della pagina bianca, ma non sostituisce la necessità di capire cosa c’è nel tuo Dockerfile.

Best practice dopo aver usato Docker init

I file generati da docker init sono un punto di partenza. Ecco i passi per trasformarli in qualcosa di pronto per la produzione.

• Rivedi i file generati: leggi riga per riga Dockerfile, .dockerignore e compose.yaml. I file sono ben commentati, quindi non ci vorrà molto. Vuoi capire cosa c’è prima di costruirci sopra

• Ottimizza la dimensione dell’immagine: la base image predefinita è python:3.x-slim, già leggera. Ma puoi fare di più assicurandoti che il tuo .dockerignore escluda tutto il necessario e verificando di non copiare nell’immagine file superflui

• Sposta i secret e i valori specifici dell’ambiente in variabili d’ambiente: non inserire hardcoded API key, URL di database o flag di ambiente nel Dockerfile. Usa variabili d’ambiente e gestiscile con un file .env in locale o con il sistema di gestione dei secret della tua piattaforma di deploy in produzione

• Testa in locale prima di pushare altrove: esegui docker compose up --build e verifica che l’app si comporti allo stesso modo dentro e fuori dal container. Controlla i log, visita gli endpoint e conferma il mapping delle porte

• Affina i passaggi di build man mano che il progetto cresce: il Dockerfile generato installa le dipendenze in un singolo layer. Quando il progetto matura, pensa all’ordinamento dei layer: metti prima i passaggi che cambiano meno spesso così Docker può metterli in cache. Se i tempi di build iniziano ad allungarsi, è di solito il primo punto da controllare

Problemi comuni e troubleshooting

Come sempre in ambito tech, possono capitare un paio di intoppi. Ecco cosa controllare e come risolvere.

Rilevamento errato del progetto

Se docker init sceglie lo stack sbagliato, genererà file che non corrispondono al tuo progetto. Di solito accade quando la cartella contiene file di linguaggi misti o manca il file che docker init si aspetta - come requirements.txt per Python o package.json per Node.js.

Quando il prompt chiede la piattaforma dell’applicazione, seleziona manualmente quella corretta invece di accettare il default rilevato.

Conflitti di porta

Se il container parte ma non riesci a raggiungere l’app, o Docker segnala che una porta è già in uso, probabilmente un altro processo sulla tua macchina occupa la stessa porta.

Individua e ferma il processo in conflitto, oppure cambia la porta lato host nel tuo compose.yaml:

ports:
  - 8001:8000  # maps host port 8001 to container port 8000

A sinistra c’è la porta sulla tua macchina. A destra deve corrispondere a quella su cui l’app è in ascolto nel container.

Dipendenze mancanti

Se il container viene costruito ma va in crash all’avvio, spesso il motivo sono dipendenze mancanti. Controlla che il tuo requirements.txt (o equivalente) sia completo e aggiornato. Se hai aggiunto un pacchetto in locale senza aggiornare quel file, il container non lo avrà.

Esegui docker compose logs per vedere l’output di errore:

docker compose logs

Di solito il messaggio di errore ti indica esattamente quale pacchetto manca.

Il container non si avvia

Se il container non parte affatto, quasi sempre il problema è nella riga CMD del tuo Dockerfile. Verifica che il comando di avvio corrisponda a come esegui davvero l’app.

Per l’esempio FastAPI dovrebbe essere così:

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Se il file di entry point ha un nome diverso o il percorso del modulo è sbagliato, il container uscirà. Correggi il CMD, ricostruisci con docker compose up --build e ricontrolla i log.

Conclusione

docker init non sostituisce una comprensione profonda di Docker, ma ti toglie dal problema della pagina bianca.

Con un solo comando ottieni un Dockerfile, un .dockerignore e un compose.yml funzionanti - tutti allineati alle best practice di Docker. È un’ottima base per qualsiasi nuovo progetto, e molto meglio di un template copiato e incollato da Stack Overflow o ChatGPT.

Solo, non fermarti lì. I file generati sono fatti per essere modificati. Rivedili, affina i passaggi di build, blocca la versione della base image e aggiungi le variabili d’ambiente. Più il progetto cresce, più ti allontanerai dai default.

Se conosci le basi di Docker, il passo logico successivo è imparare le multi-stage build, gli strumenti di rete e Docker Compose - tutto trattato nel nostro corso Intermediate Docker .