Dockerfile en Portainer: Guía Paso a Paso para Construir Imágenes

Table of Contents

Introducción a Dockerfile y Portainer

¿Te ha pasado alguna vez que estás configurando un contenedor y piensas «esto debería ser más sencillo»? Pues justo ahí es donde entra en juego el dúo Dockerfile y Portainer. Es como tener a Batman y Robin trabajando juntos en tus proyectos de contenedores.

Mira, el Dockerfile es esa receta de cocina que te saca de apuros cuando quieres replicar exactamente el mismo plato (o en este caso, tu aplicación) una y otra vez. Y Portainer… bueno, es como tener un asistente personal que te evita memorizar todos esos comandos de terminal que se te olvidan justo cuando más los necesitas.

«Lo que más me flipa de usar Dockerfile en Portainer es que de repente todo el equipo, hasta el becario que llegó la semana pasada, puede entender y colaborar en proyectos que antes parecían magia negra.»

Si ya manejas lo básico de Linux y has trasteado algo con contenedores, esto te va a encantar. Pero ojo, si todavía te suena a chino lo de «montar un contenedor», échale antes un vistazo a nuestro tutorial de Docker para principiantes donde lo explicamos como si fuera una receta de tortilla de patatas.

La cosa es que cuando juntas Dockerfile y Portainer, de repente automatizar despliegues y gestionar entornos se vuelve casi tan sencillo como pedir comida a domicilio. Y lo mejor es que no necesitas ser un gurú de DevOps para sacarle partido.

Consulta la web oficial de Portainer.

¿Te pica la curiosidad? Vamos a destripar cómo sacarle el máximo jugo a esta combinación, paso a paso y sin tecnicismos innecesarios.

¿Qué es un Dockerfile y para qué sirve?

¿Alguna vez has intentado seguir una receta de cocina donde faltaban ingredientes o los pasos no estaban claros? Pues un Dockerfile es justo lo contrario: es esa receta infalible que te asegura que tu contenedor salga perfecto cada vez que lo preparas. Básicamente, es un archivo de texto donde escribes todas las instrucciones para crear una imagen de Docker, paso a paso, sin dejarte nada en el tintero. Y si estás metido en el mundo de dockerfile portainer, dominar esto es como aprender los trucos del chef antes de entrar a una cocina profesional.

La gracia del Dockerfile es que te quita esos dolores de cabeza de «pero si en mi máquina funcionaba». Define hasta el último detalle de tu contenedor: desde qué sistema operativo usa hasta qué dependencias instalar, cómo configurarlo… vamos, todo. Así te aseguras de que tu aplicación se comporte igual estés donde estés -desde tu portátil hasta el servidor de producción- sin esas sorpresas desagradables que todos hemos tenido.

«El Dockerfile es como ese manual de instrucciones de Ikea que realmente funciona -sigues los pasos y al final tienes un mueble que no se tambalea.»

Estructura básica de un Dockerfile

Un Dockerfile se lee casi como una lista de tareas, con sus instrucciones clave:

FROM: La imagen base, tu punto de partida (como elegir el tipo de masa para una pizza)
RUN: Comandos que ejecutas durante la construcción (instalar paquetes, configurar cosas…)
COPY: Copiar archivos desde tu ordenador al contenedor
WORKDIR: Donde vas a trabajar dentro del contenedor
EXPOSE: Los puertos que «abres» para que tu app sea accesible
CMD: Lo que se ejecuta cuando arranca el contenedor

Cada instrucción añade una capa, como si estuvieras construyendo una lasaña -capa tras capa hasta tener el plato completo. Y cuando trabajas con dockerfile portainer, esta estructura se mantiene, lo que es un alivio porque ya tienes bastante con entenderlo una vez.

Ventajas de usar Dockerfile

Usar Dockerfile te cambia la vida (bueno, la vida profesional, al menos):

Reproducibilidad: Tu compañero puede construir exactamente la misma imagen que tú, sin dramas
Automatización: Se integra en tus pipelines como si llevara toda la vida ahí
Versionado: Puedes seguir los cambios como con tu código, hasta saber quién metió la pata
Eficiencia: Las capas se cachean, así que builds posteriores son más rápidos (¡bendito cache!)

Para proyectos que se van complicando y necesitan automatización más avanzada, échale un ojo a nuestra guía sobre las mejores herramientas CI/CD open source -te ahorrará más de un quebradero de cabeza.

«Un Dockerfile bien hecho es como tener un asistente que nunca se equivoca -sabes que tu contenedor va a funcionar siempre igual.»

Cuando juntas dockerfile portainer, es como tener superpoderes: toda la flexibilidad de Dockerfile con la comodidad de una interfaz web que no te hace sudar. Perfecto para equipos que quieren simplificar sin perder el control de lo que hacen.

Si te pica la curiosidad sobre cómo encaja todo esto en el mundo DevOps, no te pierdas nuestro artículo sobre DevOps: desarrollo, operaciones y mucho más -te va aclarar muchas cosas.

Oye, y si esto te ha servido, compártelo con tu equipo -seguro que más de uno te lo agradece. ¡A construir contenedores que funcionen a la primera!

Construcción de imágenes en Portainer

¿Sabías que Portainer te da hasta cuatro formas distintas de crear imágenes desde tu Dockerfile? Es como tener varias entradas al mismo concierto – cada una con sus ventajas, dependiendo de cómo te guste trabajar.

Cargar un Dockerfile pegado en texto

Esta es la opción «express» – perfecta para cuando tienes una idea y quieres probarla ya mismo. Te metes en Images, pinchas en «Build a new image» y… ¡sorpresa! Tienes un cuadro de texto enorme esperando que pegues tu Dockerfile. Sin archivos, sin complicaciones.

«Es como enviar un mensaje de texto rápido en lugar de una carta formal – ideal para esos experimentos que se te ocurren mientras tomas el café.»

Subir Dockerfile como archivo

Cuando tu proyecto empieza a crecer y necesitas algo más organizado (o sea, cuando ya tienes carpetas, archivos de configuración y esas cosas), esta es tu opción. En la misma sección de builds, eliges «Upload» y subes el archivo completo. Eso sí, acuérdate de tener todos los archivos necesarios en la misma carpeta, que si no… ya sabes cómo acaban estas historias.

Usar repositorios Git

Aquí es donde la cosa se pone interesante. Portainer se lleva de maravilla con Git, como esos amigos que se entienden sin hablar. Solo necesitas pegar la URL de tu repositorio (da igual si es GitHub, GitLab o lo que uses) y las credenciales si las pide.

URL del repositorio: https://github.com/usuario/proyecto.git
Rama: main, develop, o la que tengas de moda esta semana
Dockerfile path: /Dockerfile o donde lo hayas escondido

Lo mejor es que esto encaja perfectamente con esos workflows de automatización en GitHub que tanto molan.

Automatizar builds

¿Y si te digo que puedes hacer que Portainer construya automáticamente cuando haces un commit? Suena a magia, pero es real. Configuras un webhook en tu Git y… ¡zas! Cada vez que subas cambios, Portainer se pone manos a la obra sin que tengas que darle al botón.

«Es como tener un ayudante que vigila tu código y actúa antes de que termines de pestañear. Flipante, ¿verdad?»

Al final, elegir un método u otro es cuestión de gustos. ¿Eres de los que prueba cosas sobre la marcha? Pega el texto. ¿Tienes todo organizado en local? Sube el archivo. ¿Trabajas en equipo? Git es tu mejor aliado. Todo depende de cómo te muevas y tus necesidades de despliegue continuo.

¿Y tú? ¿Con cuál de estos métodos te quedas? Cuéntanoslo en los comentarios – seguro que tu experiencia con dockerfile portainer le viene bien a más de un desarrollador que anda perdido por ahí.

Guía paso a paso: Crear imagen en Portainer

¿Sabes esa sensación cuando tu cafetera inteligente se pone a hacer café sola mientras tú apenas has abierto los ojos? Pues construir una imagen desde un Dockerfile en Portainer puede ser igual de mágico (y bastante más útil, la verdad). Te voy a contar cómo dominar esto sin volverte loco con la terminal.

Acceso a la sección de builds

Primero, métete en tu Portainer como quien se mete en Netflix un domingo por la tarde. Una vez dentro, en el menú de la izquierda busca App Templates y dale a Custom Templates. O sea, es como buscar esa serie que sabes que está ahí pero nunca recuerdas dónde exactamente.

«La interfaz de Portainer es como tener un asistente que te hace el trabajo sucio: construye las imágenes por ti sin tener que memorizar comandos que siempre se te olvidan.»

Configuración del contexto de build

Aquí viene lo importante: el contexto. Es como cuando preparas una receta y necesitas tener todos los ingredientes a mano antes de empezar:

Local: Si tu Dockerfile está ahí mismo, en el mismo servidor
URL: Para pillar todo desde internet, como cuando descargas una app
Git Repository: Para clonar directamente del repo, que es lo que hago yo siempre

Si vas a lo local, asegúrate de que tienes el Dockerfile y todos los archivos que necesita. Vamos, como cuando vas a hacer la compra y te acuerdas de todo… o casi todo.

Definición de parámetros y variables

Esto es donde te puedes poner creativo. Portainer te deja definir variables que luego usarás en el build. ¿Para qué sirve? Pues mira:

Parámetro	Uso	Ejemplo
TAG	Le pones nombre y versión a tu imagen	mi-app:1.0
BUILD_ARGS	Variables que usa el Dockerfile	VERSION=latest

Ejecución y monitoreo del build

Cuando ya tengas todo listo, dale al botón de Build the image y prepárate para ver el espectáculo. Portainer te muestra todo en directo, como cuando ves cómo sube el bizcocho en el horno:

Va bajando las capas base si hace falta
Ejecuta cada línea de tu Dockerfile una por una
Te enseña el progreso paso a paso
Y si algo falla, te avisa al momento (menos mal)

La verdad es que construir un Dockerfile en Portainer es una gozada para los que estamos hasta el gorro de la terminal. Y si quieres ser todavía más eficiente, échale un ojo a estos alias de bash que te ahorrarán un montón de tiempo.

«Ver el build en tiempo real es como tener visión de rayos X: ves exactamente qué está pasando dentro y por qué se atasca algo, si es que se atasca.»

Cuando termine (crucemos los dedos para que todo vaya bien), tu imagen nueva estará esperándote en la sección Images, lista para usar. Esta forma de trabajar con Dockerfile en Portainer es especialmente útil cuando trabajas en equipo y no quieres que cada uno haga las cosas a su manera.

¿Cómo te ha ido con esto? Cuéntame tu experiencia construyendo imágenes con Dockerfile en Portainer en los comentarios, que seguro que a otros les viene de perlas saber cómo lo llevas tú.

Ejemplo práctico: Imagen Python con Dockerfile

Ejemplo práctico de Dockerfile Python en Portainer

¿Te ha pasado eso de querer probar algo en Python y que se te complique el entorno? Pues hoy vamos a montar una aplicación Python sencillita que te va a demostrar lo fácil que es construir una imagen usando Dockerfile en Portainer. Te prometo que cuando termines vas a decir «¡ostras, qué fácil era!»

Creación del Dockerfile

Vamos al lío. Crea un archivo Dockerfile con esto que te pongo aquí:

# Imagen base oficial de Python (la ligera, que no ocupa como un elefante)
FROM python:3.9-slim

# Donde vamos a trabajar, o sea, nuestro "despacho" dentro del contenedor
WORKDIR /app

# Esto es un truco mío: copiar requirements primero para que Docker cachee
COPY requirements.txt .

# Instalar las dependencias (sin dejar caché, que luego ocupa espacio)
RUN pip install --no-cache-dir -r requirements.txt

# Y ahora copiamos todo lo demás, como quien mete la compra en la nevera
COPY . .

# Abrimos el puerto 8000, que es como dejar la puerta de casa abierta para visitas
EXPOSE 8000

# Y esto es lo que hará que la aplicación se ponga en marcha
CMD ["python", "app.py"]

«La estructura correcta del Dockerfile es clave para builds eficientes y reproducibles en Portainer.»

Ahora toca crear los archivos de la aplicación. Primero el requirements.txt, que es cortito pero matón:

flask==2.3.3

Y el archivo principal app.py, que es más simple que el mecanismo de un chupete:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return '¡Hola desde mi aplicación Python en Docker!'

@app.route('/health')
def health():
    return {'status': 'healthy'}

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000)

Preparación del contexto

Antes de liarla en Portainer, asegúrate de tener estos tres archivos juntitos en una carpeta, como los Tres Cerditos:

Dockerfile – Las instrucciones de construcción (el plano de la casa)
requirements.txt – Las dependencias de Python (los ladrillos)
app.py – El código de la aplicación (el cerdo que vive dentro)

Si se te ha olvidado algo de Python (que a todos nos pasa), échale un ojo a nuestra guía rápida de Python para desarrolladores.

Configuración en Portainer

En Portainer, te vas a App Templates → Custom Templates y le das a «Build a new image». Configura esto que te digo:

Parámetro	Valor
Build method	Upload
Image name	mi-app-python:latest
Dockerfile location	Dockerfile

Subes los tres archivos en un zip o uno a uno (como prefieras, que aquí no mandamos). Portainer es listo y detectará el Dockerfile solito.

Verificación de la imagen

Cuando termine el build (que suele ser rápido, como un microondas), comprueba que todo ha ido bien:

# Para ver las imágenes que tienes, como quien mira su armario
docker images

# Ejecutar el contenedor (esto ya es la magia)
docker run -d -p 8000:8000 --name python-app mi-app-python:latest

# Y ahora la prueba del algodón
curl http://localhost:8000

«La verificación paso a paso es esencial para detectar problemas temprano en el proceso de construcción con Dockerfile.»

Si te pica el gusanillo de la automatización con Python, tenemos una guía sobre automatización de Excel con Python que te va a molar.

Problemas típicos (y cómo salir del atolladero):

Error: «Dockerfile not found» → Oye, que el archivo se tiene que llamar EXACTAMENTE «Dockerfile», sin extensiones raras
Error: «pip install fails» → ¿Tienes el requirements.txt en la carpeta? Que si no, pip se queja más que mi suegra
Error: «Port not exposed» → Mira que hayas puesto el EXPOSE en el Dockerfile, que si no es como tener teléfono sin batería

Y con esto ya ves cómo Portainer le quita el misterio al uso de Dockerfile para construir imágenes Python. ¡Es más fácil de lo que parece!

Cómo automatizar builds desde Git con Portainer

¿Cansado de estar pendiente de cada cambio en tu código? Te cuento cómo montar un sistema de integración continua con Portainer que funciona casi solo… ¡y lo mejor es que no necesitas ser un gurú de DevOps para hacerlo!

Configuración de webhooks

Los webhooks son como esos interruptores inteligentes que encienden las luces cuando entras en casa, pero para tus builds. Y la verdad es que una vez que los configuras, te preguntas cómo vivías sin ellos. A ver, el proceso es bastante sencillo:

Entra en Portainer y pasea por la sección de «Stacks» o «Containers»
Crea un webhook nuevo – está en esa esquina de configuración avanzada que siempre evitamos mirar
Copia esa URL rara que te genera Portainer (esa que parece contraseña de wifi)
Pégalo en tu repositorio Git favorito y… ¡ya están hablando!

«Cuando configuras bien los webhooks, Portainer se convierte en tu ayudante particular – como tener un robot que construye tus imágenes mientras tú te tomas el café.»

Integración con GitHub/GitLab

Con GitHub es más fácil que configurar la tele nueva, te lo juro:

Métete en los ajustes de tu repo en GitHub
Busca «Webhooks» por ahí en el menú lateral (a veces se esconde)
Pega esa URL que copiaste antes de Portainer
Pon «application/json» como tipo de contenido (no te líes con esto)
Elige qué eventos activarán el build – normalmente con el «push» basta, como cuando le das al botón de la cafetera

Para GitLab es parecido, solo que buscas «Integrations» en lugar de webhooks. Y si te pica el gusanillo de la automatización, puedes echarle un ojo a los n8n workflows en GitHub para cosas más elaboradas.

Automatización de despliegues

Una vez que todo está conectado… ¡magia! Cada vez que haces push:

Se construye la imagen nueva automáticamente (antes de que termines de pestañear)
Se etiqueta sola con eso del commit hash – que suena complicado pero es como ponerle nombre a las fotos
Se despliega el contenedor si lo tienes configurado
Te llegan notificaciones por si algo sale mal (que a veces pasa, somos humanos)

Para espiar qué está pasando con tus builds, el panel de eventos de Portainer es tu nuevo mejor amigo. Ahí ves todo el historial, los tiempos y esos errores raros que aparecen de vez en cuando. Así montas un flujo de dockerfile portainer que funciona casi sin que te des cuenta.

Si tu proyecto se vuelve más complejo (¡enhorabuena!), quizá quieras mirar las mejores herramientas CI/CD open source en 2025 para dar el siguiente paso.

¿Ya has probado a automatizar tus builds con dockerfile portainer? Cuéntanos cómo te fue en los comentarios – igual hasta se te ocurre algún truco que al resto se nos ha pasado.

Errores comunes al usar Dockerfile en Portainer y cómo resolverlos

Vamos a ser sinceros: trabajar con dockerfile portainer puede ser como ese momento en que tu cafetera inteligente decide no entender la app del móvil… ¡justo cuando más necesitas el café! Pero tranquilo, que estos problemillas tienen solución más fácil de lo que parece.

No encuentra Dockerfile

¿Te ha pasado eso de buscar las llaves por toda la casa y resulta que las tenías en la mano? Pues esto es igual. Portainer a veces no ve el Dockerfile donde debería, y las razones suelen ser de esas que dan un poco de vergüenza admitir:

Ruta incorrecta: Como cuando guardas un archivo en Descargas y juras que estaba en Documentos
Nombre mal escrito: «Dokerfile» sin la segunda ‘c’… nos ha pasado a todos, ¿eh?
Contexto mal definido: Básicamente, le estás diciendo que busque en el armario de la cocina cuando el archivo está en el del baño

La solución es de esas obvias: Revisa dónde metiste el bendito archivo y en Portainer, en «Dockerfile path», pon la ruta exacta. Nada de adivinanzas.

«Definir bien el contexto de build evita muchos de esos errores de dockerfile portainer que nos hacen arrancarnos los pelos.»

Buildx no soportado

Esto es como cuando intentas usar una app nueva en un móvil viejo: a veces simplemente no funciona. Buildx puede dar problemas con versiones antiguas de Docker.

Señales claras: El build falla con mensajes raros sobre Buildx
El porqué: Tu Docker necesita una actualización o la configuración está un poco… digamos, desalineada

Vamos paso a paso, que no cunda el pánico:

Mira qué versión tienes: docker --version (esto no muerde, prometo)
Si es muy antigua, actualiza – como cuando pasas de Windows 7 al 10
En Portainer, quita la opción de Buildx
Usa el builder de toda la vida, el que nunca falla

Timeout en builds largos

¿Recuerdas esas descargas que parecen eternas y justo se cortan al 99%? Pues los builds pueden ser igual de dramáticos si no ajustas el tiempo de espera.

Mi experiencia con tiempos:

Tipo de build	Timeout que suelo usar
Builds simples	10 minutos (suficiente para hacer un café)
Builds con dependencias	30 minutos (da tiempo a un capítulo de tu serie)
Builds complejos	60 minutos o más (ya puedes poner una peli completa)

Ajusta el timeout según lo complejo que sea tu dockerfile portainer. No hay nada más frustrante que un build que muere por impaciencia.

Context mal definido

Esto es como cuando llenas el maletero del coche para un fin de semana y te llevas hasta la plancha… ¡innecesario! El contexto de build incluye archivos que a veces ni necesitas.

Error típico: Meter todos los archivos del proyecto, hasta los que no pintan nada
La salvación: El .dockerignore – tu mejor amigo para no llevar equipaje extra

Un .dockerignore que funciona de verdad:

.git
node_modules
*.log
.DS_Store
# Y todo lo que te haga decir "esto para qué lo subo?"

Problemas de permisos

Los permisos en Linux son como esas fiestas a las que no te dejan entrar sin la pulsera correcta. Portainer necesita su «pulsera VIP» para acceder a los archivos.

Para verificar:

ls -la Dockerfile

La solución es simple pero vital: Asegúrate de que el usuario de Portainer pueda leer tanto el directorio como el Dockerfile. Si no, es como intentar entrar en casa con la llave del trabajo.

Si quieres profundizar en esto de los permisos (que es más interesante de lo que suena), échale un ojo a nuestra guía sobre registro de sistema en Raspberry Pi.

«Los permisos bien configurados son tan cruciales como tener un buen dockerfile portainer. Una cosa sin la otra… pues no funciona, oye.»

¿Te ha servido esta guía para esos momentos de «¿y ahora por qué no funciona?»? Comparte este artículo con ese compañero que siempre está maldiciendo el Docker – le harás un favor de esos que se agradecen de verdad.