DevOps Eterno: Guía Paso a Paso de Portainer 3 para Sysadmins Linux

Si administra uno o varios servidores Linux con Docker y todavía pelea con docker ps + docker logs -f desde SSH cada vez que un contenedor se cae, Portainer sigue siendo, en 2026, el panel web más rápido para visualizar el estado real de tu entorno. El contexto importa: el 11 de septiembre de 2026 el CEO Neil Cresswell anunció que Portainer 3.x será una línea Kubernetes-first y que Community Edition (CE) se quedará en el código 2.x recibiendo mantenimiento conjunto con la LTS de Business Edition. Eso significa que hoy, octubre de 2026, instalar Portainer CE 2.45.2 LTS sobre Docker sigue siendo la elección correcta para sysadmins y homelabs que no están listos para migrar a K8s. Esta guía es paso a paso: instalación, primer entorno, agregar hosts remotos, stacks de docker-compose y backup, todo con comandos reales probados en Debian 12 y Ubuntu 24.04 LTS.

Por qué Portainer CE 2.45 LTS, y no 3.x todavía

Antes de tocar el teclado, conviene entender dónde está parado el proyecto hoy, porque eso cambia cómo piensa la instalación:

• Portainer 2.45 LTS es el último release de la línea 2.x y recibió un parche crítico el 8 de octubre de 2026 (versión 2.45.2 LTS) que corrige varias CVEs y rompe compatibilidad con la API antigua de GitCredentials sin urlPattern. Es la base estable que vas a instalar.
• Portainer 3.x es Kubernetes-first: el equipo reposicionó todo el roadmap hacia K8s. En 3.x los entornos Docker/Podman/Swarm siguen funcionando pero quedan ordenados en segundo plano y ya no reciben nuevas capacidades del motor de políticas, GitOps ni observabilidad.
• CE no se publica en 3.x. La edición Community sigue sobre 2.45 LTS; los usuarios que quieran Portainer 3.x deben activar una licencia gratuita de Business Edition (el plan “3 nodes free”) que sigue activa.
• El roadmap sigue Docker en 2.45. El CEO fue explícito: la línea 2.x recibe bug fixes, parches de seguridad y backports selectivos de capacidades de 3.x cuando la API de Docker lo permite. No es un proyecto abandonado.

Para un homelab o servidor self-hosted con pocos nodos y stacks de docker-compose, 2.45.2 LTS sigue siendo la opción lógica. Cuando estés listo para K8s, el camino oficial es KubeSolo + Portainer 3.x (BE) o migrar a Portainer-Run; lo cubrimos al final.

Requisitos antes de instalar

Portainer corre como contenedor, así que necesitas un motor Docker funcional. La doc oficial recomienda evitar snap en Ubuntu porque mete una capa de aislamiento que rompe el socket. Asumimos Docker 24.x o superior (probado con Docker 27.x y 28.x).

• Linux x86_64 o arm64 con Docker CE / Docker Engine instalado.
• Acceso sudo al host para crear el volumen y desplegar el contenedor.
• Puertos: 9443 (UI HTTPS, obligatorio) y 8000 (túnel TCP para Edge Agents, opcional). Si vas a conectar hosts remotos sin VPN, abrí el 8000 con cuidado — está pensado para tráfico tunneled con credenciales del agente.
• SELinux desactivado o Portainer corriendo con --privileged. Rootless Docker tiene limitaciones documentadas y requiere configuración extra.
• Acceso al socket de Docker (/var/run/docker.sock). Portainer lo monta para gestionar contenedores en el mismo host donde corre; para hosts remotos, agrega un environment aparte.

Antes de seguir, verifica la versión de Docker y que el daemon esté activo. Esto evita el típico “el contenedor cae a los 5 segundos” sin saber por qué:

docker --version
sudo systemctl is-active docker
sudo docker info | head -20

Si systemctl is-active docker devuelve inactive o failed, primero arregla el motor (sudo systemctl restart docker + revisa journalctl -xeu docker.service) y recién después vuelve a este paso. Portainer depende de Docker para correr, no para inicializarse.

Instalación paso a paso con Docker Compose

La forma recomendada es Docker Compose. Creamos un directorio dedicado para que el archivo conviva limpio con tus otros stacks:

mkdir -p ~/portainer && cd ~/portainer
cat > portainer-compose.yaml <<'YAML'
services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:lts
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - "9443:9443"
      - "8000:8000"
volumes:
  portainer_data:
    name: portainer_data
YAML

El bloque volumes: declara el volumen nombrado portainer_data (la base SQLite con todos tus entornos, stacks, equipos y políticas). Montar el socket permite que Portainer vea los contenedores locales. Fíjate en el tag :lts: usar siempre la LTS te garantiza los parches de seguridad sin sorpresas. Levanta el stack con docker compose (no docker-compose, que es la versión legacy v1 ya deprecada):

docker compose -f portainer-compose.yaml up -d

El -d es importante: lanza en background y libera la terminal. Valida que el contenedor esté corriendo antes de tocar la UI:

docker compose -f portainer-compose.yaml ps
docker logs --tail 20 portainer

Si todo está OK, vas a ver en logs algo como level=info msg="http: Server listening on :9443". Si ves permission denied sobre /var/run/docker.sock, tu usuario no está en el grupo docker o SELinux está bloqueando; en Debian/Ubuntu el fix típico es sudo usermod -aG docker $USER + logout/login.

Configuración inicial y primer entorno

Una vez arriba, abre https://<tu-servidor>:9443. La primera vez Portainer exige un setup token que se imprime en logs. Lo capturas así:

docker logs portainer 2>&1 | grep -i "setup token"

Pega ese token en la UI, crea el usuario admin (no uses admin como nombre ni portainer como contraseña en producción) y entra al dashboard. En menos de 30 segundos Portainer detecta el socket local y te pregunta si quieres gestionarlo como local environment. Acepta, y ya tienes tu primer entorno.

El paso crítico, que la mayoría se salta, es desactivar la auto-creación del primer entorno como local y, en su lugar, configurar Edge Agents para nodos remotos en vez de exponer el socket por TCP. Para un single-host este paso es opcional y puedes pasar a la siguiente sección.

Agregar un host remoto con Edge Agent

Acá está el verdadero poder de Portainer: una sola UI controlando N nodos. La forma más limpia hoy es el Edge Agent, que inicia la conexión saliente hacia el server (no necesita abrir puertos en el nodo remoto). En el server:

1. Menú Environments → Add environment → Agent → Edge Agent.
2. Portainer te muestra un EDGE_ID y un comando docker run con la variable --AGENT_SECRET prellenada.

En el host remoto, ejecuta exactamente ese comando. Ejemplo adaptado (reemplaza <SERVER_IP> y <EDGE_ID> por los valores que te dio la UI):

docker run -d 
  -p 9001:9001 
  --name portainer_edge_agent 
  --restart=always 
  -v /var/run/docker.sock:/var/run/docker.sock 
  -v /var/lib/docker/volumes:/var/lib/docker/volumes 
  -v /:/host 
  -e EDGE=1 
  -e EDGE_ID=<EDGE_ID> 
  -e EDGE_INSECURE_POLL=1 
  -e CAP_HOST_CAP=1 
  portainer/agent:latest

El EDGE_INSECURE_POLL=1 permite que el agente inicie la conexión sin verificar TLS contra el server (útil si tu certificado es self-signed durante el setup). En producción deja EDGE_INSECURE_POLL=0 y monta los certificados correctos. El parámetro CAP_HOST_CAP=1 habilita la capacidad host-management: desde la UI puedes reiniciar servicios del sistema operativo del agente y leer logs de systemd. Útil pero peligroso, déjalo desactivado si no lo necesitas. Después de unos segundos el entorno remoto aparece en tu dashboard, ya puedes listar sus contenedores, imágenes y stacks desde la misma UI.

Stacks de docker-compose desde la UI

La feature más subestimada es el editor de Stacks: pega tu docker-compose.yml, define variables de entorno, y Portainer deploya, actualiza o detiene toda la pila con un click. Esto reemplaza tener que hacer SSH a cada servidor y correr docker compose up -d. Para crear uno:

1. Stacks → Add stack.
2. Nombre (slug estilo URL, ej. nginx-proxy).
3. Build method: Web editor (pegar compose) o Repository (conectar a un repo Git con GitOps).
4. Pegar tu YAML, guardar y Deploy the stack.

Esto último es clave en 2.45 LTS: si activas GitOps en un stack y le das una URL de repo, Portainer hace pull periódicamente, detecta cambios en el docker-compose.yml y redespliega solo, con rollback automático si el deploy falla. Para un servidor casero es equivalente a ArgoCD liviano, sin meter toda la complejidad de Kubernetes. Útil para mantener sincronizados tus stacks entre múltiples hosts.

Backup, actualizaciones y troubleshooting

Tres tareas que tienes que tener en automático si no quieres sorpresas:

1. Backup de la base. Portainer guarda todo (entornos, stacks, credenciales Git) en el volumen portainer_data. Un dump de SQLite te cubre 99% de los casos:

docker run --rm -v portainer_data:/data -v $(pwd):/backup 
  alpine:3.20 sh -c "cp /data/portainer.db /backup/portainer_$(date +%F).db"

Rotar semanalmente con un cron y subir a un bucket S3/B2 si tu servidor es crítico. Sin este dump, perder el contenedor significa perder todos tus entornos y stacks guardados — los contenedores en sí siguen vivos pero la UI queda vacía.

2. Actualización. La línea 2.45 LTS recibe parches de seguridad frecuentes; saltar de 2.44 a 2.45.2 LTS debería ser transparente. Procedimiento seguro, sin downtime perceptible:

docker compose -f portainer-compose.yaml pull
docker compose -f portainer-compose.yaml up -d

Antes de hacer el up -d toma un backup del paso 1. Si algo sale mal, docker compose down + restaurar el backup del volumen te deja como estabas.

3. Troubleshooting rápido. Tres casos frecuentes:

• “Container exits immediately”: revisa docker logs portainer; el 90% de las veces es un bind mount inválido o un puerto ya ocupado.
• “No se ven los contenedores del host”: problema con el socket. verifica ls -l /var/run/docker.sock y que tu usuario pertenezca al grupo docker.
• “Edge agent nunca aparece”: revisa que el 8000 esté abierto desde el agente hacia el server, y que EDGE_ID coincida exactamente. Un caracter fuera de lugar rompe la asociación silenciosamente.

Qué viene ahora en Portainer 3.x

Acá está la decisión que el anuncio de septiembre pone sobre la mesa para 2027 y más allá. La línea 2.x va a seguir recibiendo mantenimiento mientras haya clientes en producción, pero las nuevas capacidades (motor de políticas, observabilidad, GitOps avanzado, AI-grid, agentic operations vía MCP) son Kubernetes-only. Si tu homelab escala a 3-5 nodos y empiezas a pensar en alta disponibilidad, el camino natural es:

• KubeSolo: distribución Kubernetes de un solo nodo, MIT, embebida en Portainer-Run. Útil para “tener K8s sin la complejidad de un cluster multi-master”.
• Portainer-D2K: entorno Docker sintético sobre K8s que viene integrado en Portainer 3.x. Te permite migrar tus stacks actuales sin reescribirlos, ya que K8s los entiende.
• Plan “3 nodes free” de Business Edition: 3 nodos gratis, suficiente para homelabs medianos. Si te pasas, pagas.

Si por el contrario tu plan es “tengo 1-3 servidores con docker-compose y estoy cómodo así”, quedarte en 2.45 LTS con CE es totalmente válido y soportado. El blog oficial fue explícito en esto: no van a forzar la migración ni van a romper compatibilidad sin avisar con tiempo. el autor, en particular, mantiene Portainer CE 2.45 LTS como herramienta de gestión visual mientras termina de estabilizar el cluster de Kubernetes ligero que correrá los servicios del homelab — esa convivencia Docker + K8s con D2K es exactamente el caso de uso que 3.x busca hacer indoloro.

Resumen

Portainer en 2026 sigue siendo la opción pragmática para sysadmins Linux que quieren visibilidad centralizada de sus contenedores sin meterse en Kubernetes. La línea 2.45 LTS (hoy 2.45.2) es estable, sigue recibiendo parches críticos de seguridad y convivirá con la línea 3.x durante los próximos años. Instalación con Docker Compose + volumen nombrado + tag :lts te lleva de cero a UI operativa en menos de 5 minutos. Edge Agents te permiten sumar nodos remotos sin abrir puertos, y los Stacks con GitOps reemplazan el ciclo manual de docker compose pull && up en cada servidor. Empieza por CE, mantén backups de portainer.db, y cuando el crecimiento lo justifique migra a Portainer 3.x BE con KubeSolo o D2K; hasta entonces, 2.45 LTS es exactamente lo que necesitas.

Preguntas frecuentes

Lee también

• Guía Fedora 44: Novedades, Instalación y Upgrade para Sysadmins Linux
• Configura VLANs en Linux con nmcli: Guía paso a paso para sysadmins
• Protege tu SSH: Guía esencial para configurar Fail2ban en Linux
• Guía Definitiva: Configura Kubernetes con kubeadm en Ubuntu para Sysadmins Linux
• Configura Prometheus y Grafana: Guía DevOps para SysAdmins Linux