Instalación y configuración de Portainer CE

Nivel: Principiante
Tiempo para completar: ~30 minutos

Objetivo: Al completar esta guía, tendrás un panel de Portainer CE completamente configurado, asegurado con HTTPS y listo para gestionar la infraestructura Docker de tu servidor.

Introducción

La contenedorización basada en Docker se ha convertido en el estándar para la infraestructura de servidores, asegurando un despliegue predecible y una escalabilidad eficiente de servicios. Sin embargo, al ejecutar docenas de contenedores, gestionarlos únicamente a través de la línea de comandos se vuelve inconveniente. Portainer CE resuelve este problema proporcionando una interfaz web fácil de usar para la administración de Docker: proporciona acceso a todos los contenedores, sus estados, registros y recursos, y la gestión se realiza en unos pocos clics sin perder el control del sistema.

Preparación del servidor

Antes de la instalación, es necesario asegurarse de que el servidor esté listo para el despliegue de Portainer. Portainer en sí mismo se ejecuta como un contenedor, por lo que solo es necesario tener Docker instalado.

Requisitos del sistema

• Sistema operativo: Cualquier distribución de Linux (Ubuntu 20.04+, Debian 11+, CentOS/Rocky Linux 8+) utilizada en el hosting.
• Privilegios: acceso root o la capacidad de ejecutar comandos a través de sudo.
• Requisitos de hardware: Mínimo 1 GB de RAM y 10 GB de espacio libre en disco.
• Requisitos de red: Puertos abiertos 8000 y 9443 para acceso a Portainer, puerto 443 para configuración de proxy inverso.

Verificación de disponibilidad de Docker

Conéctate al servidor a través de SSH. Primero, verifica si Docker está instalado y si el demonio está en ejecución:

docker --version
sudo systemctl status docker

Si se muestra la versión de Docker y el estado es activo (en ejecución), se puede omitir el paso de instalación de Docker.

Instalación de Docker (si es necesario)

En servidores nuevos, Docker generalmente no está presente. Para instalarlo, ejecuta el script estándar (para Debian/Ubuntu):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable docker
sudo systemctl start docker

Para instalar el complemento Docker Compose (si no se instaló en el paso anterior), ejecuta:

sudo apt-get install docker-compose-plugin   # Para Debian/Ubuntu
# o
sudo dnf install docker-compose-plugin       # Para CentOS/Rocky Linux

Verifica la versión del docker compose instalado:

docker compose version

Despliegue de Portainer CE en Docker

Hay dos formas principales de ejecutar Portainer: a través del comando docker run (inicio rápido) y a través de docker-compose.yml (conveniente para la versionado de configuraciones).

Método 1: Ejecución a través de docker run

Ejecuta el siguiente comando en el servidor:

sudo docker run -d \
  -p 8000:8000 \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Explicación de los parámetros:

• -d – Ejecuta el contenedor en segundo plano.
• -p 8000:8000 – Redirección de puertos para agentes Edge y túneles.
• -p 9443:9443 – Redirección de puertos para la interfaz web segura (HTTPS). Portainer genera automáticamente un certificado SSL autofirmado.
• --name portainer – Asigna un nombre significativo al contenedor.
• --restart=always – Política de reinicio automático del contenedor en caso de fallos o reinicio del servidor.
• -v /var/run/docker.sock:/var/run/docker.sock – Monta el socket de Docker dentro del contenedor de Portainer. Esto permite que Portainer interactúe y gestione el demonio Docker en el host.
• -v portainer_data:/data – Crea un volumen nombrado para almacenar datos de Portainer (usuarios, configuraciones, configuraciones de conexión).
• portainer/portainer-ce:latest – La imagen con la última versión estable de la Community Edition.

Método 2: Ejecución a través de docker-compose

Para usar este método, crea un directorio y un archivo docker-compose.yml:

mkdir ~/portainer-docker
cd ~/portainer-docker
nano docker-compose.yml

Inserta el siguiente contenido:

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
volumes:
  portainer_data:

Guarda el archivo y ejecuta el comando:

docker compose up -d

Lanzamiento inicial y configuración de la interfaz web

Después de que el contenedor de Portainer se inicie, se vuelve accesible a través de la red.

Paso 1. Conexión a la interfaz web

Abre un navegador y ve a: https://<dirección-IP-del-servidor>:9443.

Paso 2. Creación de un usuario

En la página de registro, deberás especificar un nombre de usuario (se recomienda admin) y establecer una contraseña segura.

Paso 3. Conexión del entorno

Después de crear el usuario, Portainer te pedirá que conectes entornos. En esta etapa, puedes conectar el Docker local (ya disponible gracias al socket montado) o proceder a agregar entornos remotos a través del botón "Add Environments". Los entornos remotos son útiles cuando necesitas gestionar múltiples servidores desde una única interfaz de Portainer: por ejemplo, agregando hosts Docker en diferentes centros de datos o servidores con Kubernetes. La conexión se realiza a través de agentes de Portainer o a través de la API utilizando certificados TLS.

• Selecciona la opción "Get Started". Este es el escenario básico para un solo servidor.

• Portainer detectará automáticamente el socket Docker local. Se mostrará como "local".

• Haz clic en él para completar la configuración.

La configuración está completa. El panel de Portainer (pantalla principal) se abrirá con estadísticas breves sobre contenedores, imágenes, volúmenes y redes.

Características principales de Portainer

Veamos las principales secciones de la interfaz que se utilizan para tareas diarias de administración.

Panel de control

La pantalla de inicio que muestra la imagen general: el número de contenedores en ejecución y detenidos, el número de imágenes descargadas. Permite evaluar rápidamente el estado del servidor.

Contenedores

• La sección central de gestión. Muestra una lista de todos los contenedores.
• Gestión de contenedores: Iniciar, detener, reiniciar, eliminar un contenedor con un solo clic.
• Registros: La pestaña "Logs" proporciona acceso a la visualización de registros de contenedores en tiempo real.
• Inspeccionar: Muestra información completa sobre el contenedor en formato JSON: variables de entorno, puntos de montaje, configuraciones de red.
• Estadísticas: Gráficos de consumo de CPU, memoria y red para cada contenedor. Ayuda a determinar el consumo de recursos por servicios individuales.
• Consola Exec: Capacidad para abrir una terminal web dentro de un contenedor para ejecutar comandos.

Pilas

Implementación de Docker Compose en la interfaz web. Permite cargar o crear archivos YAML directamente a través del navegador para desplegar aplicaciones de múltiples contenedores.

Imágenes

• Gestión de imágenes Docker.
• Descargar: Capacidad para descargar imágenes (por ejemplo, nginx:latest o mysql:8.0) directamente desde la interfaz.
• Eliminar: Limpieza de imágenes no utilizadas para liberar espacio en disco.

Volúmenes

Gestión de volúmenes de datos persistentes. Muestra los volúmenes existentes, su conexión a contenedores y el espacio que ocupan. Críticamente importante para bases de datos y datos de usuario.

Redes

Permite crear redes aisladas para la interacción de contenedores.

Revertir cambios (Eliminación de Portainer)

Si necesitas eliminar completamente Portainer y sus datos del servidor, sigue estos pasos:

1. Detener y eliminar el contenedor de Portainer:

sudo docker stop portainer
sudo docker rm portainer

2. Eliminar el volumen de datos de Portainer (advertencia: esta acción es irreversible):

sudo docker volume rm portainer_data

3. Eliminar la imagen de Portainer (opcional):

sudo docker rmi portainer/portainer-ce:latest

Seguridad y recomendaciones

Para producción, se requiere una configuración de seguridad adicional de Portainer.

Uso de un Proxy Inverso (Nginx/Apache)

Se recomienda configurar un subdominio (por ejemplo, portainer.dominio.com) y redirigir el tráfico a través de Nginx. Esto proporcionará:

• Uso de un certificado SSL válido (gratuito de Let's Encrypt o un SSL de pago, por ejemplo, de Sectigo).
• Registro centralizado de accesos.
• Capacidad para configurar autenticación adicional.

1. Instalación y configuración de Nginx

Instala Nginx:

sudo apt install -y nginx              # Para Debian/Ubuntu
# o
sudo dnf install -y nginx              # Para CentOS/Rocky Linux

Crea un archivo de configuración para Portainer:

sudo nano /etc/nginx/sites-available/portainer.conf

Agrega la siguiente configuración, reemplazando <YOUR_DOMAIN> con tu dominio que apunta a la IP del servidor:

server {
    listen 80;
    server_name ;
    location / {
        proxy_pass https://localhost:9443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # Tiempos de espera para operaciones largas
        proxy_connect_timeout 600;
        proxy_send_timeout 600;
        proxy_read_timeout 600;
        send_timeout 600;
    }
}

Activa la configuración:

sudo ln -s /etc/nginx/sites-available/portainer.conf /etc/nginx/sites-enabled/

Verifica la configuración de Nginx:

sudo nginx -t

Si la verificación es exitosa, reinicia Nginx:

sudo systemctl restart nginx

2. Configuración de HTTPS (recomendado)

Instala Certbot:

sudo apt install -y certbot python3-certbot-nginx

Obtén un certificado SSL:

sudo certbot --nginx -d 

Reemplaza <YOUR_DOMAIN> con tu dominio.

Durante la instalación, ingresa tu correo electrónico, por ejemplo, admin@<YOUR_DOMAIN>, luego presiona Y dos veces.

Verifica la renovación automática del certificado:

sudo systemctl list-timers | grep certbot

Configuración del firewall

El acceso directo a los puertos de Portainer debe estar restringido. Permite el acceso a los puertos 8000 y 9443 solo desde direcciones IP de confianza.

Ejemplo para UFW:

sudo ufw allow from 192.168.1.0/24 to any port 9443 proto tcp
sudo ufw deny 9443

Dónde 192.168.1.0/24 es la subred de direcciones IP de confianza.

Actualizaciones regulares

Se recomienda seguir el lanzamiento de nuevas versiones de Portainer y actualizar el contenedor a tiempo para eliminar posibles vulnerabilidades.

Verificación de operación

Para verificar que Portainer está funcionando correctamente, realiza las siguientes acciones.

1. Verificación visual: En la sección "Contenedores", asegúrate de que el contenedor portainer tenga un estado de ejecución.

2. Creación de un contenedor de prueba:

• Ve a la sección "Contenedores", haz clic en el botón "Add container".
• En el campo "Name", especifica test-nginx.
• En el campo "Image", especifica nginx:alpine.
• En la sección "Port mapping", especifica puerto del host 8080, puerto del contenedor 80.
• Haz clic en "Deploy the container".

3. Verificación de accesibilidad:

• Espera a que el contenedor aparezca en la lista con un estado de ejecución.
• Abre un navegador y ve a http://<YOUR_IP_ADDRESS>:8080. Debería mostrarse la página de bienvenida de Nginx.

4. Verificación de gestión:

• En Portainer, encuentra el contenedor test-nginx y haz clic en el botón "Stop".
• Actualiza la página de Nginx en el navegador: el acceso debería estar no disponible.
• Haz clic en "Start": el acceso a la página debería ser restaurado.

Solución de problemas

Problema 1: No se puede abrir la interfaz web de Portainer en https://<YOUR_IP_ADDRESS>:9443

Causa posible: El firewall está bloqueando el puerto 9443.

Solución: Verifica las reglas del firewall y asegúrate de que el puerto esté abierto. Para UFW: sudo ufw status | grep 9443.

Problema 2: Error "Cannot connect to the Docker daemon" al ejecutar comandos de Docker.

Causa posible: El demonio Docker no está en ejecución, o al usuario le faltan permisos.

Solución: Inicia el demonio: sudo systemctl start docker. Si agregaste el usuario al grupo docker, cierra sesión y vuelve a iniciarla.

Problema 3: El contenedor de Portainer no se inicia y sale inmediatamente (estado exited).

Causa posible: Conflicto de puertos o una imagen corrupta.

Solución: Verifica si el puerto 9443 está ocupado por otra aplicación: sudo ss -tulpn | grep 9443. Intenta reasignar el puerto y reiniciar el contenedor: sudo docker restart portainer.

Conclusión

Portainer CE proporciona una herramienta efectiva para el monitoreo visual y la gestión de contenedores Docker. La capacidad de evaluar rápidamente el estado de los contenedores, analizar gráficos de consumo de recursos y realizar operaciones típicas sin conectarse a través de SSH reduce el tiempo de respuesta a incidentes y simplifica la administración diaria.

Esta herramienta puede ser útil cuando es necesario proporcionar acceso limitado a la gestión de contenedores a desarrolladores o personal menos experimentado sin otorgar acceso directo a la línea de comandos del servidor. Portainer CE es una solución estándar para visualizar la infraestructura de contenedores y se recomienda para su uso en servidores.

Versión del documento: 1.1
Última actualización: Marzo 2026
Propietario: Equipo de Documentación Técnica