Interfaz y entornos

Con Portainer instalado y el admin creado, conviene orientarse en la interfaz antes de operar. Toda la administración gira en torno al concepto de environment (entorno).

El modelo mental: entornos primero

Cuando entrás, Portainer te muestra la lista de entornos conectados. Cada entorno es una plataforma de contenedores (un host Docker, un cluster Swarm, un cluster K8s). Elegís uno y entrás a gestionarlo; todas las operaciones —contenedores, stacks, volúmenes— ocurren dentro del contexto de ese entorno.

flowchart TD
    H["Home<br/>(lista de entornos)"] --> E1["Entorno: local"]
    H --> E2["Entorno: servidor-prod"]
    E1 --> R["Dashboard del entorno"]
    R --> C["Containers"]
    R --> S["Stacks"]
    R --> I["Images / Volumes / Networks"]

La pantalla Home

La página inicial lista los entornos con un resumen de cada uno: estado (up/down), número de stacks, contenedores corriendo/parados, uso de CPU y memoria. Desde acá:

• Hacés clic en un entorno para entrar a gestionarlo.
• Usás + Add environment para conectar uno nuevo.
• Filtrás y agrupás entornos con tags y groups (útil cuando tenés muchos).

El dashboard de un entorno

Al entrar a un entorno verás un dashboard con tarjetas de resumen: contadores de stacks, contenedores, imágenes, volúmenes y redes. Cada tarjeta es un acceso directo a la sección correspondiente. Es tu punto de partida para saber “qué hay” en ese host.

Navegación lateral

El menú de la izquierda agrupa los recursos del entorno. En un entorno Docker standalone verás, entre otros:

Sección	Qué gestionás
Dashboard	Resumen del entorno
App Templates	Despliegue rápido desde plantillas
Stacks	Aplicaciones multi-contenedor (Compose)
Containers	Contenedores individuales
Images	Imágenes locales y pull/build
Networks	Redes Docker
Volumes	Volúmenes de datos
Events	Eventos recientes del daemon
Host	Info del host, motor, setup

Arriba del todo, un selector te permite cambiar de entorno sin volver al Home. Abajo, según tu rol, aparecen las secciones de administración (usuarios, registries, settings).

Conectar un host Docker remoto (agent)

El entorno local ya está listo. Para gestionar otro host desde el mismo Server, instalás un agent en ese host y lo conectás.

En el host remoto:

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

Luego, en Portainer: Environments → Add environment → Docker Standalone → Agent, y pasás la dirección IP_DEL_HOST:9001. El Server se conecta al agent y el nuevo entorno aparece en el Home.

¿Por qué un agent y no conectarse al socket directamente? El agent expone una API pensada para Portainer (con TLS mutuo opcional), maneja correctamente los volúmenes y, en Swarm/K8s, federa la información de todos los nodos. Conectarse al socket TCP de Docker directamente es posible pero menos seguro y más limitado.

Tags y groups

Cuando administrás muchos entornos, dos herramientas te ordenan:

• Environment groups: agrupás entornos (ej. “producción”, “staging”) y aplicás permisos o despliegues por grupo.
• Tags: etiquetas libres (ej. region:us, tipo:edge) para filtrar y para definir Edge Groups dinámicos más adelante.

Acceso por API

Todo lo que hace la UI lo podés hacer por la API REST. Generás un API token desde tu perfil de usuario (My account → Access tokens) y lo usás en el header X-API-Key. Es la base para automatizar e integrar Portainer con tus pipelines.

---

Anterior → Capítulo 2: Instalación · Siguiente → Capítulo 4: Contenedores