Dominando Docker Run: Opciones Esenciales del Comando Explicadas

docker run crea un nuevo contenedor a partir de una imagen y lo inicia. El comando parece simple al principio, pero las opciones determinan cómo tu contenedor se conecta a la red, almacena datos, recibe configuración y se comporta después de un reinicio.

Usa esta guía cuando sepas la imagen que deseas ejecutar pero necesites las banderas adecuadas para una configuración práctica.

Sintaxis Básica

docker run [OPCIONES] IMAGEN [COMANDO] [ARG...]

IMAGEN es el nombre de la imagen, como nginx o postgres:16. COMANDO y ARG... son opcionales y anulan o extienden el comando predeterminado de la imagen.

Para una prueba rápida en primer plano:

docker run hello-world

Para servicios reales, normalmente agregas opciones.

Ejecutar en Segundo Plano con -d

Por defecto, Docker adjunta tu terminal a la salida del contenedor. El modo desacoplado ejecuta el contenedor en segundo plano:

docker run -d nginx

Docker imprime el ID del nuevo contenedor y devuelve tu prompt. Verifícalo con:

docker ps

Lee los registros de un contenedor desacoplado con:

docker logs <id_o_nombre_del_contenedor>

Publicar Puertos con -p

Los contenedores tienen su propio espacio de nombres de red. Si un servicio escucha dentro del contenedor, publica el puerto para alcanzarlo desde tu host:

docker run -d -p 8080:80 nginx

Esto mapea el puerto del host 8080 al puerto del contenedor 80, por lo que http://localhost:8080 llega a Nginx.

Puedes publicar más de un puerto:

docker run -d -p 8080:80 -p 8443:443 nginx

Para enlazar solo a localhost en el host, incluye la IP del host:

docker run -d -p 127.0.0.1:8080:80 nginx

Esto es útil para herramientas locales que no deseas exponer en todas las interfaces del host.

Persistir Datos con Volúmenes

Las capas de escritura del contenedor no son un buen lugar para datos duraderos. Usa un montaje de enlace cuando quieras una ruta específica del host montada dentro del contenedor:

docker run -d -p 8080:80 -v "$PWD/html:/usr/share/nginx/html:ro" nginx

Esto sirve archivos desde tu directorio local html. El sufijo :ro hace que el montaje sea de solo lectura dentro del contenedor.

Usa un volumen con nombre cuando Docker deba gestionar la ubicación de almacenamiento:

docker run -d --name postgres -v pgdata:/var/lib/postgresql/data postgres:16

Si pgdata no existe, Docker lo crea. Inspecciona los volúmenes con:

docker volume ls

Para trabajos nuevos, la sintaxis --mount de Docker es más verbosa pero más clara:

docker run -d --mount type=volume,src=pgdata,dst=/var/lib/postgresql/data postgres:16

Pasar Configuración con -e y --env-file

Las variables de entorno son una forma común de configurar aplicaciones contenerizadas:

docker run -d -e APP_ENV=production my-custom-app:latest

Usa -e más de una vez para múltiples variables:

docker run -d -e DB_HOST=database.example.com -e DB_USER=app my-app:latest

Para muchas variables, usa un archivo de entorno:

docker run -d --env-file ./app.env my-app:latest

Mantén los secretos fuera de los archivos .env comprometidos. Las variables de entorno son fáciles de inspeccionar desde el host y desde procesos con suficiente acceso, así que usa el gestor de secretos de tu plataforma para valores sensibles en producción.

Nombrar Contenedores con --name

Docker puede generar un nombre, pero un nombre claro facilita los comandos posteriores:

docker run -d --name web -p 8080:80 nginx

Luego puedes usar:

docker logs web
docker stop web
docker exec -it web sh

Los nombres de los contenedores deben ser únicos. Si web ya existe, elimina o renombra el contenedor antiguo antes de reutilizar el nombre.

Usar Modo Interactivo con -it

Para shells y sesiones de solución de problemas, combina el modo interactivo y un pseudo-TTY:

docker run -it ubuntu bash

Cuando sales del shell, el contenedor se detiene. Agrega --rm para sesiones desechables:

docker run --rm -it alpine sh

Elegir una Política de Reinicio

Las políticas de reinicio le indican a Docker qué hacer cuando un contenedor termina:

docker run -d --name web --restart unless-stopped -p 8080:80 nginx

Las políticas comunes son:

• no: no reiniciar automáticamente. Este es el valor predeterminado.
• on-failure[:max-retries]: reiniciar solo después de un código de salida distinto de cero.
• always: reiniciar cada vez que el contenedor se detiene, incluso después de reinicios del demonio Docker.
• unless-stopped: reiniciar a menos que hayas detenido explícitamente el contenedor.

Para servicios locales de larga duración, unless-stopped suele ser una mejor opción que always porque una parada manual sigue siendo respetada.

Eliminar Contenedores Desechables con --rm

Los contenedores detenidos permanecen en el disco hasta que los elimines. Para comandos de una sola vez, --rm limpia el contenedor después de que termina:

docker run --rm ubuntu echo "Hola desde un contenedor temporal"

No uses --rm para contenedores cuyo estado detenido necesites inspeccionar más tarde.

Ejemplo Práctico

Este comando ejecuta una aplicación web con un nombre estable, un puerto publicado, un directorio de registros montado por enlace, una variable de entorno y una política de reinicio:

docker run -d \
  --name my-app \
  --restart on-failure \
  -p 3000:80 \
  -v "$PWD/logs:/app/logs" \
  -e NODE_ENV=production \
  my-node-app:1.0

Después de que se inicie, verifica el contenedor y revisa los registros:

docker ps
docker logs my-app

Conclusión

Comienza con el comando docker run más pequeño que funcione, luego agrega opciones para el comportamiento que necesitas: -d para servicios en segundo plano, -p para acceso, -v o --mount para datos, -e para configuración, --name para operaciones, --restart para resiliencia y --rm para ejecuciones temporales.