Cómo instalar Portainer en un VPS Linux

Instalar Portainer en un VPS Linux

Portainer es una interfaz web para Docker. En lugar de hacerlo todo por SSH, ves contenedores, imágenes, volúmenes y stacks de Docker Compose en un panel, con botones para arrancar, parar, leer logs o desplegar un archivo Compose. El proyecto es de código abierto: el código está en el repositorio oficial de GitHub.

Esta guía cubre Portainer Community Edition (CE), la edición gratuita. Encaja bien en un VPS personal o un laboratorio pequeño. La interfaz oficial está solo en inglés, así que las etiquetas de las capturas coinciden con lo que verás tras la instalación.

Al terminar tendrás:

• un contenedor Portainer que Docker reinicia solo
• una cuenta de administrador protegida con contraseña
• Docker local ya detectado y listo para gestionarse en el navegador
• el puerto 9443 limitado a tu IP, con 8000 y 9000 dejados cerrados

Así se ve el panel cuando Docker local ya está conectado: menú a la izquierda, barra superior, datos del entorno y, en el centro, los contadores (stacks, contenedores, imágenes, volúmenes, redes).

El plan

Si Docker ya funciona en el VPS, se resume en cinco gestos:

1. Crea el volumen portainer_data y arranca el contenedor oficial.
2. Abre https://xxxx:9443/ en el navegador (certificado autofirmado en la primera visita).
3. Recupera el setup token en los logs y crea el admin en menos de cinco minutos.
4. Pulsa Get Started para quedarte en Docker local.
5. Restringe el puerto 9443: Portainer habla con Docker con los mismos derechos que root.

Requisitos previos

Antes de pegar los comandos:

• estás conectado como root en un VPS Linux de BoxToPlay, en general Ubuntu 24.04 o Debian 12 y más recientes
• Docker ya funciona. Si no, empieza por Instalar Docker en Linux, guía práctica para empezar
• el puerto TCP 9443 no lo usa otro servicio
• puedes autorizar el puerto 9443/tcp en el cortafuegos hardware de tu espacio de cliente BoxToPlay, solo desde tu IP, antes de arrancar Portainer

Docker debe venir del repositorio oficial, no de un paquete snap de Ubuntu. Portainer lo desaconseja, y nuestra guía de Docker ya usa la secuencia get.docker.com.

Paso 1: arrancar Portainer

Crea primero el volumen que guarda la base interna de Portainer (usuarios, ajustes, historial). Sin ese volumen, un simple docker rm borra también la cuenta admin.

docker volume create portainer_data

Descarga explícitamente la última imagen LTS para no reutilizar una versión antigua que haya quedado en la caché de Docker:

docker pull portainer/portainer-ce:lts

Lanza después la imagen oficial con la etiqueta lts, no latest. Es la recomendación actual de Portainer para un servidor.

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:lts

Respecto a la documentación oficial, simplificamos tres puntos:

• no publicamos el puerto 8000. Sirve al túnel de los Edge agents. En un VPS único que solo gestiona su propio Docker no lo necesitas
• no publicamos el puerto HTTP 9000 por defecto. El acceso normal es HTTPS en 9443. El 9000 solo existe para marcadores antiguos
• el montaje de /var/run/docker.sock es de lectura-escritura, como en el procedimiento oficial. Una versión :ro rompería la creación de contenedores desde la interfaz

Comprueba que el contenedor está Up:

docker ps --filter name=portainer

Ejemplo de salida:

CONTAINER ID   IMAGE                        STATUS         PORTS                                                             NAMES
a1b2c3d4e5f6   portainer/portainer-ce:lts   Up 8 seconds   8000/tcp, 9000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp   portainer

Los 8000/tcp y 9000/tcp sin 0.0.0.0 son puertos expuestos por la imagen, no publicados en el VPS. No escuchan en Internet. Solo 9443 está realmente abierto, también en IPv6 si Docker lo mapea.

Si de verdad necesitas el HTTP antiguo además del HTTPS, añade -p 9000:9000 al docker run. No es el camino que recomendamos.

Paso 2: crear el primer administrador

Abre en el navegador:

https://xxxx:9443/

Sustituye xxxx por la IP pública o el DNS de tu VPS. En la primera carga, el navegador muestra un aviso de certificado: Portainer genera un certificado autofirmado hasta que le des uno real. Es lo esperado. Continúa solo si estás en tu máquina.

Una instancia nueva de Portainer CE exige un setup token. Sin ese token, cualquiera que alcance el puerto 9443 en los primeros minutos podría autoproclamarse admin. El token es de un solo uso, solo para crear la primera cuenta o restaurar una copia de seguridad.

Muéstralo en los logs:

docker logs portainer

Busca setup_token=. Copia solo la cadena hexadecimal larga que sigue, nada más. La FAQ oficial del setup token describe el mismo gesto.

Tienes cinco minutos para crear el usuario. Pasado ese plazo, Portainer rechaza el setup por seguridad. Si ocurre, usa el bloque plegable al final de este artículo: reiniciar el contenedor genera un token nuevo.

La pantalla se parece a esta. La contraseña debe tener al menos 12 caracteres. El nombre propuesto es admin; puedes cambiarlo.

Escribe la contraseña dos veces, pega el setup token y pulsa Create user. No dejes esa contraseña en un repositorio, un ticket o un canal de Discord.

Paso 3: quedarse en Docker local

Justo después se abre el Environment Wizard. Portainer ya ha visto el socket Docker del VPS. En un servidor único, pulsa Get Started. Add Environments sirve para enlazar otros hosts (agent, Kubernetes, nube). Aquí no hace falta. Esa pantalla aparece una sola vez: el siguiente inicio de sesión abre Home directamente.

Llegas a la página Home. El entorno se llama local, el estado Up, y la URL mostrada es el socket Unix /var/run/docker.sock. Pulsa esa tarjeta para abrir el dashboard de Docker.

Paso 4: contenedores y stacks

El menú izquierdo cubre el día a día:

• Containers: lista, start/stop, logs, consola
• Images: lo que ya está descargado
• Volumes y Networks
• Stacks: desplegar un archivo Docker Compose

La lista de contenedores, justo después de instalar, suele mostrar solo Portainer:

Stacks empieza vacío. Lo más simple: Add stack, un nombre (por ejemplo web), el Compose pegado en el editor y Deploy the stack. Git y la subida también existen si los prefieres.

Un ejemplo mínimo para comprobar que un despliegue web funciona. Deja Nginx accesible solo desde el propio VPS en 127.0.0.1:8080. Para exponerlo a Internet, elige explícitamente una publicación pública y protege ese puerto en el cortafuegos hardware de BoxToPlay.

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"
    restart: unless-stopped

Una vez desplegado, el stack web aparece en Stacks, y el contenedor suele llamarse web-web-1 en Containers. Arranque, parada y logs se hacen desde la interfaz, sin volver a teclear docker compose por SSH.

Seguridad: trata Portainer como un acceso root

Montar docker.sock no es un detalle. Quien pueda iniciar sesión en Portainer puede, en la práctica, lanzar cualquier contenedor, montar el disco del host y convertirse en root del VPS. La contraseña admin no es «otro login más»: es la llave de la máquina.

Configura el cortafuegos hardware de BoxToPlay antes del docker run y permite 9443/tcp solo desde tu IP, nunca desde 0.0.0.0/0. Revisa también la regla IPv6 si tu VPS tiene una dirección IPv6. Completa el setup inmediatamente después, sin dejar Portainer abierto «para más tarde».

Un puerto publicado por Docker puede saltarse las reglas UFW clásicas. Un comando como ufw allow 9443/tcp también permitiría todas las IP de origen en lugar de limitar el acceso a la tuya. Del mismo modo, una regla añadida a la cadena iptables INPUT no filtra correctamente el tráfico reenviado hacia un contenedor Docker.

Para añadir una restricción directamente en el VPS, usa la cadena DOCKER-USER con la IP de origen y la interfaz de red reales. Es una configuración avanzada que depende de la red del servidor, así que no pegues una regla genérica a ciegas. El cortafuegos hardware de BoxToPlay sigue siendo la forma más sencilla de limitar el acceso antes del primer arranque.

No publiques 8000 hasta que tengas Edge agents de verdad, y no compartas la URL de Portainer, ni siquiera «solo el rato de instalar». Portainer ya tiene autenticación web: una Basic Auth extra en el reverse proxy no es obligatoria. Sigue siendo útil si quieres un DNS y un certificado Let’s Encrypt limpios.

Actualizar y hacer copias de seguridad

Los datos duraderos viven en el volumen portainer_data. Para actualizar:

docker pull portainer/portainer-ce:lts
docker stop portainer
docker rm portainer

Vuelve a lanzar exactamente el mismo docker run que en la instalación (mismos puertos, mismos volúmenes, misma etiqueta lts). No recrees el volumen: cuentas y ajustes se quedan.

Para una copia manual, para el contenedor y archiva el volumen, o haz un snapshot del VPS desde el espacio de cliente BoxToPlay antes de una actualización importante. El volumen con nombre portainer_data sobrevive a docker rm, también con la opción -v. La instalación solo se borra si eliminas ese volumen explícitamente, por ejemplo con docker volume rm portainer_data después de retirar el contenedor.

docker stop portainer
docker start portainer
docker logs portainer

Y después

Portainer no sustituye las copias de seguridad, el cortafuegos ni las actualizaciones del sistema. Es práctico cada día, y peligroso si queda abierto a Internet.

Si buscas un VPS Linux entregado con acceso root, listo para Docker y con cortafuegos hardware en el espacio de cliente, puedes lanzar tu servidor en BoxToPlay.