Cómo usar Portainer para gestionar contenedores Docker (paso a paso)

Ferramentas & Produtividade · Por Kevin Marcondes · Publicado el 29/09/2026 · Actualizado el 10/10/2026 · 9 min de lectura

Monitor con terminal en primer plano y una lista de servicios desenfocada — Pantalla con terminal y lista de servicios, ilustrando administración de contenedores Foto: Brett Sayles / Pexels

Esta guía muestra, de forma práctica, cómo usar Portainer para gestionar contenedores Docker: desde la instalación hasta el despliegue de stacks, control de volúmenes y redes, revisión de logs y medidas de seguridad. En pocos pasos tendrás un panel web para operar tus entornos locales o remotos con más seguridad y menos comandos.

Qué es Portainer y cuándo es útil

Portainer es un panel web que simplifica la administración de entornos Docker. Reduce errores en tareas operativas y estandariza despliegues mediante la interfaz o stacks (Compose).

Es útil cuando tu equipo necesita:

- Visualizar contenedores, volúmenes y redes de forma centralizada.

- Estandarizar despliegues con Compose, sin depender únicamente de la CLI.

- Gestionar múltiples hosts locales y remotos.

Si aún evalúas cuándo usar contenedores en lugar de máquinas virtuales, consulta un comparativo práctico: Docker vs máquinas virtuales para HA.

Prerequisitos y entorno de prueba

Antes de empezar, asegura lo siguiente:

- Un host con Docker Engine instalado y acceso sudo.

- Puertos de red abiertos: 9443/TCP para la UI; 9001/TCP para el Agent remoto.

- Navegador actualizado para acceder al panel web.

- Opcional: un segundo host Docker para probar el Agent remoto.

Atención: mapear el archivo /var/run/docker.sock a containers otorga acceso administrativo al Docker. Usa esto solo en hosts de confianza y aplica controles de acceso en la red y en el sistema.

1) Instalar Portainer CE en el host Docker

La instalación mínima usa un volumen persistente para los datos de Portainer y publica la interfaz segura en el puerto 9443. Requiere acceso root o sudo.

Ejecuta los comandos abajo en el host que ya tenga Docker. Espera a que el container inicie y comprueba que el puerto 9443 esté accesible en tu red local.

# 1) Criar volume persistente para dados do Portainer
sudo docker volume create portainer_data

# 2) Subir o Portainer CE com HTTPS (9443)
sudo docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

# 3) Verificar status
sudo docker ps --filter name=portainer
# Acesse https://SEU_HOST:9443 no navegador (certificado pode ser autoassinado).

2) Primer acceso y creación del usuario administrador

Accede a https://SEU_HOST:9443 en el navegador. En la primera pantalla, define el usuario y la contraseña del administrador.

A continuación, elige el tipo de entorno a gestionar. Para comenzar, selecciona el propio Docker local (Local). Verás el dashboard con contenedores, imágenes, volúmenes y redes.

Buenas prácticas iniciales:

- Crea una contraseña fuerte y guárdala en un gestor de contraseñas.

- Desactiva puertos públicos que no vayan a usarse. Prefiere exponer vía VPN o túnel seguro.

- Crea tags y grupos de entornos para organizar hosts.

3) Conectar hosts remotos con el Portainer Agent

Para gestionar servidores Docker remotos, instala el Portainer Agent en cada host y conéctalos desde el panel. Abre el puerto 9001/TCP en el firewall y garantiza que solo Portainer pueda acceder a él.

En el host remoto, ejecuta el Agent. Después, en Portainer, agrega un nuevo entorno del tipo Agent e indica la dirección del host remoto:9001.

# No host REMOTO (com Docker instalado)
sudo docker run -d \
  -p 9001:9001 \
  --name portainer_agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:latest

# Após subir, no Portainer UI: Environments > Add environment > Agent
# Informe: tcp://IP_DO_HOST_REMOTO:9001

4) Despliegue de contenedores y stacks (Compose)

Puedes levantar contenedores individuales o stacks usando archivos Compose. Los stacks facilitan el versionado y la replicación entre entornos.

Flujo común:

- Crear una stack, pegar el YAML del Compose, ajustar variables y desplegar.

- Parametrizar variables con .env y Secrets.

- Validar logs y el estado de salud del servicio tras el despliegue.

La siguiente tabla ayuda a localizar acciones típicas en la UI y su equivalente conceptual en la CLI.

Tarea	Dónde en la UI	Equivalente en la CLI
Subir container único	Containers > Add container	docker run
Subir stack Compose	Stacks > Add stack	docker compose up -d
Mapear puerto/volumen	Form de container/stack	-p / -v
Ver logs	Container > Logs	docker logs -f
Reiniciar/escalar	Container/Stack > Actions	docker restart / compose scale

# Exemplo de stack (Compose v3+): Web + Redis
a version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - web_content:/usr/share/nginx/html:ro
    depends_on:
      - cache
  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
volumes:
  web_content: {}
  redis_data: {}

Volúmenes, redes, variables y seguridad en la práctica

Volúmenes: prefiere volúmenes con nombre para persistencia. Para backup, copia los datos fuera del host o comprime el volumen periódicamente.

Redes: usa redes bridge personalizadas por proyecto para aislar el tráfico entre servicios. Evita compartir redes sin necesidad.

Variables y secrets: almacena credenciales como Secrets y usa variables de entorno para parámetros. No incluyas contraseñas dentro de la imagen.

Seguridad:

- Restringe el acceso a la UI (9443) mediante VPN, lista blanca de IPs o proxy inverso.

- Activa HTTPS y evita exponer el puerto 9001 públicamente.

- Revisa quién puede tocar el Docker socket y el host.

Automatización: tras dominar lo básico, conecta tus despliegues a pipelines de CI/CD. Consulta un guía práctico: CI/CD con GitHub Actions (PHP/Laravel) para adaptar al stack.

Los logs estructurados ayudan mucho en el diagnóstico. Si aún no estandarizas logs, revisa el guía de logs estructurados (JSON) y correlación.

# Exemplos úteis (executar no host conforme seu ambiente)

# Backup simples do volume do Portainer (gera arquivo no diretório atual)
sudo docker run --rm \
  -v portainer_data:/data \
  -v "$(pwd)":/backup \
  alpine sh -c "tar czf /backup/portainer_data.tgz -C / data"

# Atualizar o Portainer mantendo os dados
sudo docker pull portainer/portainer-ce:latest
sudo docker stop portainer && sudo docker rm portainer
sudo docker run -d -p 9443:9443 \
  --name portainer --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Verificación del entorno y resolución de problemas comunes

Tras instalar y configurar, valida que todo esté saludable:

- La UI abre en https://SEU_HOST:9443 sin errores críticos.

- Ves contenedores, volúmenes y redes del host Local.

- El Agent remoto aparece en Environments con estado up.

- Los logs del container de prueba no muestran fallos recurrentes.

Problemas comunes y correcciones:

- Puerto 9443/9001 bloqueado: ábrelos en el firewall y en el proveedor.

- Permisos en el Docker socket: el proceso necesita acceso a /var/run/docker.sock.

- DNS y pull de imágenes: revisa la red externa del host.

- Certificado auto-firmado: añade una excepción temporal o usa un proxy con TLS válido.

- En WSL2/desktop, confirma la IP correcta del host.

Para madurar operaciones y auditar cambios de despliegue, vale la pena estudiar procesos y checklists como los discutidos en auditoría de procesos de deploy.

# Verificações rápidas
sudo docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | sed -n '1,10p'

# Logs do Portainer (últimas 100 linhas)
sudo docker logs --tail=100 portainer

# Testar conectividade com Agent remoto (da máquina do Portainer)
# Substitua IP_PEER pelo endereço do host remoto
nc -vz IP_PEER 9001 || telnet IP_PEER 9001 || echo "Falha na conexão"

Preguntas frecuentes

¿Puedo usar Portainer en producción?

Sí, Portainer se usa en entornos de operación, pero su adopción en producción depende de tus requisitos de seguridad y gobernanza. Antes de desplegarlo ampliamente, restringe el acceso a la UI (9443), aplica HTTPS y controles de red, prueba la configuración en un entorno de homologación y revisa permisos sobre el Docker socket y los hosts para minimizar riesgos operativos.

¿Portainer sustituye a docker-compose?

No reemplaza docker-compose: Portainer orquesta stacks basados en archivos Compose y facilita desplegarlos desde la interfaz. Sigues manteniendo el mismo YAML de Compose; la ventaja es poder visualizar, parametrizar y versionar stacks desde el panel, lo que reduce fricción operativa sin cambiar el formato y la definición que ya usas con docker-compose.

¿Cómo proteger el acceso al Docker socket?

Evita exponer /var/run/docker.sock por la red y monta el socket solo localmente para Portainer cuando sea necesario. Limita quién puede acceder al host, aplica el principio de menor privilegio, mantiene el sistema actualizado y audita cuentas y credenciales. Para entornos expuestos, usa controles de red (VPN, listas blancas) y revisa regularmente qué procesos tienen acceso al socket.

¿Necesito Kubernetes para usar Portainer?

No, no necesitas Kubernetes: Portainer gestiona Docker puro de forma completa y permite administrar contenedores, volúmenes y redes. Si en el futuro migras a Kubernetes, Portainer también puede integrarlo, pero empezar y operar únicamente con Docker es totalmente válido y soportado por la herramienta descrita en la guía.

¿Cómo hago backup de los datos de Portainer?

Los datos de Portainer se guardan en el volumen mapeado en /data. Haz copias periódicas de ese volumen hacia almacenamiento externo o utiliza un contenedor temporal para compactarlo y exportarlo. Programa backups regulares y valida las restauraciones en un entorno de prueba para asegurarte de que los datos y la configuración se recuperan correctamente.

¿Es posible integrar con CI/CD?

Sí. Puedes automatizar despliegues de stacks desde pipelines que actualicen imágenes y reinicien servicios o actualicen la definición del stack. Planifica el manejo de variables y secrets, la promoción entre entornos y pruebas automatizadas. La integración facilita actualizaciones reproducibles siempre que tus pipelines gestionen correctamente las credenciales y la orquestación del despliegue.

¿Listo para operar tus contenedores con menos fricción?

Sigue el paso a paso, prueba en un entorno aislado y evoluciona con logs estructurados, backups y automatización de despliegues. Comienza hoy con el entorno local y conecta tus hosts remotos con el Agent.

Revisar comandos e iniciar ahora