Docker init: cómo inicializar un proyecto con Docker (guía paso a paso)

Por algún motivo, poner en marcha un proyecto nuevo con Docker siempre lleva más tiempo del que debería.

Buscas una plantilla en Google, la pegas, cambias un par de líneas y cruzas los dedos. La build falla, así que tocas algo y repites el ciclo hasta que funciona. Cada proyecto nuevo empieza igual: con un archivo en blanco y un recuerdo borroso de lo que funcionó la última vez. Es un claro problema de configuración, y Docker no tiene la culpa.

La buena noticia es que docker init lo soluciona. Es un comando de la CLI que detecta el tipo de proyecto y genera un Dockerfile, un .dockerignore y un archivo de Compose.

En este artículo te explico cómo funciona docker init, cómo usarlo paso a paso con un proyecto real en Python y cuándo es la herramienta adecuada.

¿Eres totalmente nuevo en Docker y la contenerización? Descubre por qué es una parte esencial del kit de todo profesional de datos con nuestro curso de Introduction to Docker.

Qué es Docker init

docker init es una herramienta de línea de comandos que configura Docker para tu proyecto. Genera los archivos que necesitas para contenerizar tu app. Así que no hacen falta plantillas ni copiar y pegar.

Genera tres archivos:

• Dockerfile: define cómo se construye la imagen del contenedor
• .dockerignore: indica a Docker qué archivos debe excluir del contexto de build
• compose.yml: opcional, pero muy útil para configuraciones con varios servicios

La parte inteligente es la detección automática del proyecto. docker init revisa la estructura y averigua qué stack usas (Python, Node.js, Go, y otros). Luego genera archivos adaptados a ese stack en lugar de una plantilla genérica.

No es una herramienta de despliegue ni gestionará tus contenedores en producción. Simplemente arranca la configuración para que puedas centrarte en el trabajo real.

Cómo funciona Docker init

docker init sigue un flujo de cuatro pasos cada vez que lo ejecutas.

Primero ejecutas docker init dentro de la carpeta de tu proyecto. Docker escanea el directorio, detecta el tipo de proyecto y elige la plantilla adecuada. Después te guía con un breve asistente interactivo: cosas como en qué puerto se ejecuta tu app y qué comando la inicia. Una vez respondido, genera los archivos.

Todo el proceso lleva menos de un minuto.

Las preguntas son sencillas y rara vez necesitan explicación adicional. Puedes aceptar los valores por defecto pulsando Intro o escribir los tuyos si no encajan.

Esto es lo que verás al ejecutar el comando por primera vez:

Pantalla de configuración de Docker init

A continuación te muestro el proceso con más detalle.

Cómo usar Docker init paso a paso

Resumen de cómo pasar de una carpeta de proyecto a un contenedor en ejecución.

Paso 1: navega hasta el directorio de tu proyecto

Abre la terminal y ve a la raíz de tu proyecto: la carpeta que contiene el código de tu aplicación.

cd /path/to/your/project

docker init genera archivos relativos al directorio en el que se ejecuta, así que asegúrate de estar en el correcto antes de continuar.

Paso 2: ejecuta Docker init

Ejecuta el siguiente comando:

docker init

Docker escaneará la carpeta, detectará tu stack y lanzará el asistente de configuración interactivo.

Paso 3: responde a las preguntas

docker init te preguntará un par de cosas:

• Plataforma de la aplicación: el lenguaje o framework que usa tu proyecto (Python, Node.js, Go, etc.)
• Puerto: el puerto en el que escucha tu app
• Comando de inicio: el comando que Docker debe ejecutar para arrancar tu app

Puedes aceptar los valores sugeridos pulsando Intro o escribir los tuyos. Si docker init detecta tu stack, los valores por defecto suelen ser suficientes para empezar.

Paso 4: revisa los archivos generados

Cuando termines, docker init escribirá tres archivos en la carpeta del proyecto:

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

Abre cada archivo y léelo. Los archivos generados incluyen comentarios que explican cada línea, así que merece la pena dedicar unos minutos a entender qué se ha creado antes de construir nada.

Paso 5: construye y ejecuta tu contenedor

Compila y arranca tu contenedor con Docker Compose:

docker compose up --build

La opción --build le dice a Docker que construya la imagen a partir de tu Dockerfile antes de iniciar el contenedor. Una vez en marcha, tu app debería ser accesible en el puerto que especificaste en el paso 3.

Tipos de proyecto compatibles con Docker init

docker init es compatible de serie con los stacks de aplicaciones más comunes. Algunos ejemplos:

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

Detecta el stack automáticamente. Cuando ejecutas docker init, escanea la carpeta en busca de archivos específicos del lenguaje (como requirements.txt en Python o package.json en Node.js) y elige la plantilla adecuada según lo que encuentre.

Cada plantilla está adaptada al stack. Un proyecto en Python recibe una imagen base, comandos de instalación y comando de inicio distintos a los de un proyecto en Go. No es un Dockerfile genérico con una variable de lenguaje: la estructura cambia según lo que estés construyendo.

Si docker init no puede detectar tu stack, te pedirá que lo elijas manualmente de una lista.

Archivos que genera Docker init

docker init genera tres archivos, y cada uno cumple una función distinta en tu configuración.

Dockerfile

El Dockerfile define cómo construye Docker la imagen de tu contenedor. Indica desde qué imagen base partir, cómo instalar dependencias y qué comando ejecutar al iniciar el contenedor.

Este es un ejemplo de Dockerfile generado para Python:

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

Conviene revisarlo antes de construir. El resultado es un buen punto de partida, pero puede que necesites ajustarlo: por ejemplo, añadir variables de entorno o fijar la versión de la imagen base.

.dockerignore

El archivo .dockerignore indica a Docker qué archivos excluir del contexto de build. Es el conjunto de archivos que Docker envía al motor de build al crear tu imagen.

Sin él, Docker copiaría todo lo que hay en tu carpeta de proyecto dentro de la imagen, incluido .git, node_modules o configuraciones locales que no necesitas en producción. Eso aumenta el tamaño de la imagen y puede exponer archivos que no pretendías incluir.

Un .dockerignore típico puede verse así:

.git
.env
__pycache__
*.pyc
node_modules

Archivo de Docker Compose

El archivo compose.yaml sirve para ejecutar configuraciones con varios contenedores. Define servicios, puertos, volúmenes y cómo se conectan entre sí los contenedores.

Para una app sencilla de un solo contenedor puede que no lo necesites. Pero si tu proyecto incluye una base de datos, un sistema de caché u otro servicio junto a tu app, aquí es donde lo configuras todo en un único sitio.

Ejemplo: usar Docker init con un proyecto en Python

Vamos a ejecutar docker init en un proyecto real. Usaré una app mínima de FastAPI con una única ruta como ejemplo.

Esta es la estructura del proyecto antes de ejecutar docker init:

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

app.py tiene una única ruta Hello World:

from fastapi import FastAPI

app = FastAPI()

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

Y requirements.txt incluye estas dos dependencias:

fastapi
uvicorn

Ejecutar docker init

Para empezar, navega a la carpeta del proyecto y ejecuta:

docker init

Proyecto detectado por Docker init

docker init detecta Python a partir de requirements.txt y te hace un par de preguntas. Así se ven los prompts y esto es lo que debes responder:

Prompts de Docker init para un proyecto en Python

Qué se genera

Tras responder, tu carpeta de proyecto queda así:

Nueva estructura de la carpeta del proyecto

Hay tres archivos nuevos. Veámoslos.

El 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

Hay varios detalles interesantes. PYTHONDONTWRITEBYTECODE=1 evita que Python escriba archivos .pyc en disco, y PYTHONUNBUFFERED=1 garantiza que los logs aparezcan en tiempo real en lugar de quedarse en un buffer: dos buenos valores por defecto para apps contenerizadas.

El bloque adduser crea un usuario sin privilegios llamado appuser para ejecutar la aplicación. Por defecto, los contenedores Docker se ejecutan como root, lo que supone un riesgo de seguridad. Ejecutar como usuario no root limita lo que podría hacer un atacante si consigue salir de tu app.

La opción --mount=type=cache en el paso de pip install indica a Docker que almacene en caché los paquetes descargados entre builds. Así, las siguientes builds no volverán a descargar dependencias desde cero y ganarás velocidad.

El .dockerignore

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

El .dockerignore excluye archivos que no deben ir en tu imagen. Archivos de entorno locales como .env, carpetas de control de versiones como .git y cachés de Python como __pycache__ se omiten. El propio Dockerfile y compose.yaml también quedan fuera: Docker no los necesita dentro de la imagen que está construyendo.

El compose.yaml

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

El archivo de Compose define tu app como un servicio llamado server, lo construye a partir del Dockerfile del directorio actual y mapea el puerto 8000 del host al 8000 del contenedor.

Los tres archivos generados incluyen comentarios que he omitido para simplificar.

Ejecuta docker compose up --build y tu app de FastAPI estará disponible en http://localhost:8000.

App de FastAPI ejecutándose en un contenedor

Docker init vs configuración manual del Dockerfile

Ambos enfoques te dan un Dockerfile funcional. La diferencia está en cuánto control necesitas y con qué rapidez quieres llegar.

Docker init

docker init es la opción más rápida. Respondes a unas pocas preguntas y en menos de un minuto obtienes una configuración funcional y razonablemente segura. Los archivos generados siguen las mejores prácticas de Docker (usuarios no root, caché de build, patrones adecuados en .dockerignore), así que no empiezas de cero.

Encaja bien cuando arrancas un proyecto nuevo, estás incorporando a alguien al equipo o quieres una base sólida sin perder tiempo en boilerplate.

La pega es la flexibilidad. Las plantillas cubren bien los casos comunes, pero siguen siendo plantillas. Si tu proyecto tiene una estructura poco habitual o requisitos específicos de build, te toparás con los límites de lo que docker init puede generar.

Configuración manual

Escribir tu Dockerfile a mano te da control total sobre cada capa, cada instrucción y cada decisión de build. Puedes implementar builds multietapa para minimizar el tamaño de la imagen, usar imágenes base personalizadas o afinar el comportamiento de la caché de formas que docker init no puede anticipar.

Eso sí, necesitas saber lo que haces. Un Dockerfile mal escrito puede generar imágenes gigantes, introducir problemas de seguridad o fallar de formas difíciles de depurar, sobre todo si no tienes experiencia.

Cuál usar

Una forma sencilla de verlo:

Comparativa: Docker init vs configuración manual

Un buen enfoque es empezar con docker init y después editar a mano los archivos generados según vayan creciendo tus necesidades.

Cuándo usar Docker init

docker init no es la herramienta adecuada para todo. Aquí tienes cuándo tiene sentido y cuándo no.

Elige docker init cuando:

• Empiezas un proyecto nuevo: te pone la configuración de Docker en marcha en menos de un minuto, para que puedas centrarte en escribir código y no en la contenerización

• Estás aprendiendo Docker: los archivos generados están bien comentados y siguen buenas prácticas. Son un mejor punto de partida que un snippet aleatorio de Stack Overflow

• Estás prototipando: cuando necesitas un entorno contenerizado rápido y no te importa afinar la build, docker init te da algo que funciona

• Quieres estandarizar en un equipo: en lugar de que cada persona haga su propio Dockerfile, docker init da a todo el mundo un punto de partida coherente con la misma estructura y valores por defecto

En cambio, evita docker init cuando:

• Necesitas builds multietapa: si optimizas el tamaño de la imagen separando la build en etapas (compilas en una y ejecutas en otra), tendrás que escribirlo a mano. El Dockerfile generado es de una sola etapa

• Tienes requisitos complejos de producción: imágenes base personalizadas, estrategias avanzadas de caché, estructuras no estándar... docker init no puede anticiparlo. Perderás más tiempo sorteando los archivos generados que escribiendo los tuyos

En resumen, docker init es un punto de partida. Úsalo para arrancar y edita los archivos a medida que crezcan tus necesidades.

Limitaciones de Docker init

A medida que tu proyecto crece, pueden aparecer limitaciones. Algunas de ellas:

Los archivos generados están basados en plantillas. Cubren los casos más comunes para cada stack, por lo que funcionan bien para proyectos típicos y peor para los atípicos. Si tu proyecto tiene una estructura poco común, es posible que no lo contemplen.

Otra limitación habitual es que casi siempre necesitarás ajustes manuales. Los valores por defecto son buenos, pero siguen siendo por defecto. Seguramente tengas que fijar la versión de la imagen base, ajustar variables de entorno o modificar el comando de inicio para que encaje con tu proyecto. Piensa en los archivos generados como un primer borrador, nada más.

docker init tampoco admite patrones de build avanzados. Builds multietapa, argumentos de build personalizados, lógica condicional y otras técnicas habituales en imágenes de producción quedan fuera del alcance de la herramienta. Pero si necesitas eso, de todos modos acabarás escribiendo el Dockerfile a mano.

Nada de esto convierte a docker init en una mala herramienta. Solo significa que debes ir con las expectativas correctas: elimina el síndrome de la hoja en blanco, pero no sustituye entender qué hay en tu Dockerfile.

Mejores prácticas después de usar Docker init

Los archivos que genera docker init son un punto de partida. Estos son los pasos para llevarlos a producción.

• Revisa los archivos generados: lee el Dockerfile, el .dockerignore y el compose.yaml línea a línea. Están bien comentados, así que no te llevará mucho. Quieres entender qué hay antes de construir encima

• Optimiza el tamaño de tu imagen: la imagen base por defecto es python:3.x-slim, ya de por sí ligera. Aún puedes ir más allá asegurándote de que tu .dockerignore excluye todo lo que debe y comprobando que no copias archivos innecesarios a la imagen

• Mueve secretos y valores específicos de entorno a variables de entorno: no hardcodes claves de API, URLs de base de datos ni flags de entorno en tu Dockerfile. Usa variables de entorno y gestiona su ciclo de vida con un archivo .env en local o el gestor de secretos de tu plataforma en producción

• Prueba en local antes de subir nada: ejecuta docker compose up --build y verifica que tu app se comporta igual dentro del contenedor que fuera. Revisa los logs, accede a los endpoints y confirma que el mapeo de puertos funciona

• Refina los pasos de build conforme crezca el proyecto: el Dockerfile generado instala dependencias en una sola capa. A medida que el proyecto madura, piensa en el orden de las capas: pon antes los pasos que cambian menos para que Docker pueda cachearlos. Si los tiempos de build aumentan, suele ser lo primero que revisar

Problemas comunes y cómo resolverlos

Como siempre en tecnología, pueden surgir un par de cosas. Esto es lo que debes mirar y cómo arreglarlo.

Detección incorrecta del proyecto

Si docker init elige el stack equivocado, generará archivos que no encajan con tu proyecto. Suele pasar cuando tu carpeta mezcla lenguajes o falta el archivo que docker init espera (como requirements.txt en Python o package.json en Node.js).

Cuando el asistente pregunte por la plataforma de tu aplicación, selecciona manualmente la correcta en lugar de aceptar la detectada.

Conflictos de puertos

Si el contenedor arranca pero no puedes acceder a la app, o Docker muestra un error de puerto en uso, probablemente otro proceso de tu máquina ocupa ese puerto.

Detén el proceso en conflicto o cambia el puerto del host en tu compose.yaml:

ports:
  - 8001:8000  # mapea el puerto 8001 del host al 8000 del contenedor

La parte izquierda es el puerto de tu máquina. La derecha debe coincidir con el puerto en el que escucha tu app dentro del contenedor.

Dependencias faltantes

Si la imagen se construye pero el contenedor se cae al iniciar, suele deberse a dependencias faltantes. Comprueba que tu requirements.txt (o equivalente) esté completo y actualizado. Si añadiste un paquete en local sin actualizar ese archivo, el contenedor no lo tendrá.

Ejecuta docker compose logs para ver el error:

docker compose logs

El mensaje de error suele indicar exactamente qué paquete falta.

El contenedor no arranca

Si el contenedor ni siquiera arranca, casi siempre el problema está en la línea CMD de tu Dockerfile. Verifica que el comando de inicio coincide con cómo ejecutas tu app realmente.

Para el ejemplo de FastAPI, debería verse así:

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

Si el archivo de entrada tiene otro nombre o la ruta del módulo es incorrecta, el contenedor saldrá. Corrige el CMD, reconstruye con docker compose up --build y revisa los logs de nuevo.

Conclusión

docker init no sustituye entender Docker a fondo, pero sí te saca del síndrome de la hoja en blanco.

Con un solo comando obtienes un Dockerfile, un .dockerignore y un compose.yml funcionales, todos siguiendo las mejores prácticas de Docker. Es una base estupenda para cualquier proyecto nuevo y mucho mejor punto de partida que una plantilla copiada de Stack Overflow o ChatGPT.

Eso sí, no te quedes ahí. Los archivos generados están pensados para editarlos. Revísalos, ajusta los pasos de build, fija la versión de la imagen base y añade tus variables de entorno. Cuanto más crezca el proyecto, más te alejarás de los valores por defecto.

Si ya dominas lo básico de Docker, el siguiente paso lógico es aprender sobre builds multietapa, herramientas de red y Docker Compose; todo ello cubierto en nuestro curso Intermediate Docker .