Implementación de Portainer CE en Docker para la gestión de contenedores

Nivel: Principiante
Tiempo estimado: ~30 minutos
Objetivo: Al finalizar esta guía, dispondrás de un panel de Portainer CE totalmente configurado, protegido con HTTPS y listo para gestionar la infraestructura de Docker de tu servidor. Al finalizar esta guía, dispondrás de un panel de Portainer CE totalmente configurado, protegido con HTTPS y listo para gestionar la infraestructura de Docker de tu servidor.

Introducción

La contenedorización basada en Docker se ha convertido en el estándar para la infraestructura de servidores, lo que garantiza una implementación predecible y un escalado eficiente de los servicios. Sin embargo, cuando se ejecutan docenas de contenedores, gestionarlos únicamente a través de la línea de comandos resulta poco práctico. Portainer CE resuelve este problema al ofrecer una interfaz web intuitiva para la administración de Docker: permite acceder a todos los contenedores, sus estados, registros y recursos, y la gestión se realiza con 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 la implementación de Portainer. El propio Portainer se ejecuta como un contenedor, por lo que solo es necesario instalar Docker.

Requisitos del sistema:

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

Comprobación de la disponibilidad de Docker

Conéctate al servidor mediante SSH. En primer lugar, comprueba si Docker está instalado y si el daemon se está ejecutando:

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 los servidores nuevos, Docker no suele estar 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   # For Debian/Ubuntu
# or
sudo dnf install docker-compose-plugin       # For CentOS/Rocky Linux

Comprueba la versión de Docker Compose instalada:

docker compose version

Implementación de Portainer CE en Docker

Hay dos formas principales de ejecutar Portainer: mediante el comando `docker run` (inicio rápido) y mediante el archivo `docker-compose.yml` (práctico para el control de versiones de la configuración).

Método 1: Ejecución mediante «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

sudo usermod -aG docker $USER

Tras ejecutar el comando, debes cerrar sesión y volver a iniciarla, o reiniciar tu sesión.

Explicación de los parámetros:

• -d: ejecuta el contenedor en segundo plano.
• -p 8000:8000: reenvío de puertos para los agentes Edge y los túneles.
• -p 9443:9443: reenvío 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 a Portainer interactuar con el daemon de Docker en el host y gestionarlo.
• -v portainer_data:/data – Crea un volumen con nombre para almacenar los datos de Portainer (usuarios, ajustes, 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 mediante docker-compose

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

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

Introduce 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

Inicio inicial y configuración de la interfaz web

Una vez iniciado el contenedor de Portainer, se puede acceder a él a través de la red.

Paso 1. Conexión a la interfaz web

Abre un navegador y ve a: https://:9443.

Debido al uso de un certificado autofirmado, el navegador mostrará una advertencia. Debes continuar con el acceso al sitio.

Paso 2. Creación de un usuario

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

Paso 3. Conectar el entorno

Tras crear el usuario, Portainer te pedirá que conectes entornos. En esta fase, puedes conectar el Docker local (ya disponible gracias al socket montado) o añadir entornos remotos mediante el botón «Añadir entornos».

Los entornos remotos resultan útiles cuando necesitas gestionar varios servidores desde una única interfaz de Portainer: por ejemplo, al añadir hosts de Docker en diferentes centros de datos o servidores con Kubernetes. La conexión se establece a través de los agentes de Portainer o mediante la API utilizando certificados TLS.

• Selecciona la opción «Empezar». Este es el escenario básico para un único servidor.



• Portainer detectará automáticamente el socket de Docker local. Aparecerá como «local».



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

La configuración ha finalizado. Se abrirá el panel de control de Portainer (pantalla principal) con estadísticas breves sobre contenedores, imágenes, volúmenes y redes.

Características principales de Portainer

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

Panel de control

La pantalla de inicio que muestra una visión general: el número de contenedores en ejecución y detenidos, y el número de imágenes descargadas. Te 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 o eliminar un contenedor con un solo clic.
• Registros: la pestaña «Registros» permite consultar los registros de los contenedores en tiempo real.
• Inspeccionar: muestra información completa sobre el contenedor en formato JSON: variables de entorno, puntos de montaje y configuración de red.
• Estadísticas: Gráficos del consumo de CPU, memoria y red de cada contenedor. Ayuda a determinar el consumo de recursos por parte de cada servicio.
• Consola de ejecución: Posibilidad de abrir un 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 con varios contenedores.

Imágenes

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

Volúmenes

Gestión de volúmenes de datos persistentes. Muestra los volúmenes existentes, su asociación a los contenedores y el espacio que ocupan. De vital importancia para las bases de datos y los datos de los usuarios.

Redes

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

Deshacer cambios (eliminar Portainer)

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

1. Detén y elimina el contenedor de Portainer:

sudo docker stop portainer
sudo docker rm portainer

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

sudo docker volume rm portainer_data

3. Elimina la imagen de Portainer (opcional):

sudo docker rmi portainer/portainer-ce:latest

Seguridad y recomendaciones

Para entornos de 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.domain.com) y redirigir el tráfico a través de Nginx. Esto proporcionará:

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

1. Instalación y configuración de Nginx

Instala Nginx:

sudo apt install -y nginx              # For Debian/Ubuntu
# or
sudo dnf install -y nginx              # For CentOS/Rocky Linux

Crea un archivo de configuración para Portainer:

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

Añade la siguiente configuración, sustituyendo por tu dominio que apunte a la IP del servidor:

server {
    listen 80;
    server_name <YOUR_DOMAIN>;

    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;
        
        # Timeouts for long operations
        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/

Comprueba la configuración de Nginx:

sudo nginx -t

Si la comprobación se realiza correctamente, 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 <your_domain></your_domain>

Sustituye por tu dominio.

Durante la instalación, introduce tu correo electrónico, por ejemplo, admin@, y luego pulsa Y dos veces.

Marca la opción de renovación automática del certificado:

sudo systemctl list-timers | grep certbot

Configuración del cortafuegos

El acceso directo a los puertos de Portainer debe restringirse. Permite el acceso a los puertos 8000 y 9443 únicamente 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

Donde 192.168.1.0/24 es la subred de direcciones IP de confianza.

Actualizaciones periódicas

Se recomienda estar al tanto del lanzamiento de nuevas versiones de Portainer y actualizar el contenedor oportunamente para eliminar posibles vulnerabilidades.

Comprobación del funcionamiento

Para comprobar que Portainer funciona correctamente, realice las siguientes acciones.

1. Comprobación visual: en la sección «Contenedores», asegúrate de que el contenedor de Portainer tiene el estado «en ejecución».
2. Creación de un contenedor de prueba:
   • Vaya a la sección «Contenedores» y haga clic en el botón «Añadir contenedor».
   • En el campo «Nombre», introduce test-nginx.
   • En el campo «Imagen», especifica «nginx:alpine».
   • En la sección «Asignación de puertos», especifica el puerto del host 8080 y el puerto del contenedor 80.
   • Haz clic en «Implementar el contenedor».
3. Comprobación de accesibilidad:
   • Espera a que el contenedor aparezca en la lista con el estado «En ejecución».
   • Abre un navegador y ve a http://<TU_DIRECCIÓN_IP>:8080. Debería aparecer la página de bienvenida de Nginx.
4. Comprobación de gestión:
   • En Portainer, busca el contenedor «test-nginx» y haz clic en el botón «Detener».
   • Actualiza la página de Nginx en el navegador; el acceso debería estar bloqueado.
   • Haz clic en «Start»: el acceso a la página debería restablecerse.

Solución de problemas

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

Posible causa: el cortafuegos está bloqueando el puerto 9443.
Solución: Comprueba las reglas del cortafuegos y asegúrate de que el puerto está abierto. Para UFW: sudo ufw status | grep 9443.

Problema 2: Error «No se puede conectar con el demonio de Docker» al ejecutar comandos de Docker.

Posible causa: El daemon de Docker no se está ejecutando o el usuario carece de permisos.
Solución: Inicia el daemon: sudo systemctl start docker. Si has añadido al usuario al grupo docker, cierra la sesión y vuelve a iniciarla.

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

Posible causa: conflicto de puertos o una imagen dañada.
Solución: Comprueba si el puerto 9443 está ocupado por otra aplicación: `sudo ss -tulpn | grep 9443`. Intenta reasignar el puerto y reinicia el contenedor: `sudo docker restart portainer`.

Conclusión

Portainer CE ofrece una herramienta eficaz para la supervisión y gestión visual de contenedores Docker. La capacidad de evaluar rápidamente el estado de los contenedores, analizar gráficos de consumo de recursos y realizar operaciones habituales sin necesidad de conectarse vía SSH reduce el tiempo de respuesta ante incidencias y simplifica la administración diaria.

Esta herramienta puede resultar útil cuando es necesario proporcionar un acceso limitado a la gestión de contenedores a desarrolladores o personal con menos experiencia, sin concederles 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 su uso en servidores.

---

Versión del documento: 1 .1
Última actualización: marzo de 2026
Responsable: Equipo de documentacióntécnica