Tutoriais

Portainer

Tutorial completo de Portainer CE — gerenciamento de containers Docker via UI, stacks GitOps, agents, Edge, SSO via OAuth2 e RBAC.

Guia completo para configurar Portainer Community Edition como camada de gerenciamento sobre um stack Docker. Foco em visualizacao/auditoria, operacao mobile (sem SSH) e gerenciamento multi-host (servidor publico + servidor interno).


1. Visao geral

O que e o Portainer

Portainer e uma UI web para gerenciar ambientes Docker, Docker Swarm e Kubernetes. Ele se conecta ao Docker socket (ou a um Agent remoto) e expoe via navegador todas as operacoes que voce normalmente faria via CLI: containers, imagens, volumes, redes, stacks (compose), registries, secrets/configs.

A filosofia central e a abstracao de Stack — um docker-compose gerenciado pela UI, com versionamento basico, variaveis de ambiente nomeadas, deploy/redeploy idempotente e integracao GitOps.

CE vs Business Edition (BE)

RecursoCE (free)BE (paid)
Containers / Images / Volumes / NetworksSimSim
Stacks (compose)SimSim
Multi-environment (Agent / Edge)SimSim
OAuth / OIDCSimSim
RBAC granular por recursoLimitado (env-level)Sim (per-resource)
Activity logs / Audit logsBasicoCompleto
Edge Compute (jobs, configs)LimitadoCompleto
GitOps por stackSimSim
Suporte oficialComunidadeSLA
CustoGratisPor node/mes

Para 1-3 nos, CE basta. Audit log avancado e RBAC fino sao os principais diferenciais BE.

Comparacao com alternativas

FerramentaForcaLimitacao
Portainer CEStacks GitOps, multi-host, OAuth, registries, web terminalUI as vezes lenta com muitos containers
YachtUI minimalista, leveProjeto em alpha, pouco mantido
DockgeFoco em compose, hot reload de YAML, mais leveSingle-host, sem RBAC, sem registries
LazydockerTUI rapida, sem servidorLocal-only, sem mobile
Komodo (ex-Monitor)GitOps-first, builds, alertasCurva de aprendizado maior

Portainer e o ponto otimo para o caso de uso: voce mantem docker compose via SSH como fonte de verdade quando esta no desktop, e usa o Portainer para inspecao + operacoes pontuais via mobile.


2. Arquitetura

flowchart TB
    subgraph User["Usuario"]
        Browser["Browser / Mobile<br/>portainer.example.com"]
    end

    subgraph Server["Servidor publico Debian 13"]
        Nginx["nginx-proxy<br/>:80/:443 + LE"]
        Portainer["Portainer Server<br/>portainer/portainer-ce:lts<br/>UI :9000 (HTTP)<br/>UI :9443 (HTTPS)<br/>Edge tunnel :8000"]
        DockerSock1["/var/run/docker.sock"]
        Apps["postgres, keycloak,<br/>git server, registry,<br/>object storage, vpn"]
        Portainer -->|gerencia| DockerSock1
        DockerSock1 -.->|controla| Apps
        Nginx -->|reverse proxy| Portainer
    end

    subgraph Internal["Servidor interno (futuro)"]
        AgentInternal["Portainer Agent<br/>portainer/agent:latest<br/>:9001 TLS"]
        DockerSock2["/var/run/docker.sock"]
        AgentInternal --> DockerSock2
    end

    subgraph Edge["Host NAT / mobile (futuro)"]
        EdgeAgent["Edge Agent<br/>(outbound only)"]
    end

    Registry["Registries<br/>registry.example.com<br/>(privado)"]

    Browser -->|HTTPS| Nginx
    Portainer -->|TLS :9001<br/>(inbound do server)| AgentInternal
    EdgeAgent -.->|outbound HTTPS :8000<br/>NAT-friendly| Portainer
    Portainer -->|pull/push| Registry

Pontos chave:

  • Portainer Server roda em um host (o servidor principal), com acesso ao Docker socket local.
  • Hosts remotos entram como Environments. Tres modos:
    • API Docker socket exposta via TCP+TLS (nao recomendado em internet aberta).
    • Portainer Agent (:9001) — Portainer Server conecta de saida para o Agent. Bom para LAN/VPN.
    • Edge Agent — Agent que faz conexao outbound para :8000 do Server. Funciona atras de NAT/CGNAT sem port forwarding.
  • Kubernetes e suportado como tipo de environment (KubeConfig ou Agent K8s). Fora de escopo deste tutorial.

3. Pre-requisitos

  • Host Linux com Docker Engine 20.10+ e Compose v2 (docker compose).
  • Volume persistente para /data do Portainer (config, DB SQLite, certs).
  • Dominio + DNS apontando para o servidor (ex.: portainer.example.com).
  • nginx-proxy + Let’s Encrypt ja existentes em /opt/docker/.
  • Network proxy (172.28.0.0/16) ja criada.
  • Acesso ao Keycloak para configurar SSO (opcional, mas recomendado).

Verifique:

docker --version            # >= 20.10
docker compose version      # >= 2.0
docker network ls | grep proxy

4. Instalacao Portainer Server via docker compose

Crie o diretorio e arquivo:

mkdir -p /opt/docker/portainer
cd /opt/docker/portainer

/opt/docker/portainer/docker-compose.yaml:

services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    command: >
      --http-enabled
      --bind :9000
      --tunnel-port 8000
    ports:
      # HTTP interno - apenas no loopback ou na rede proxy
      # NAO publicar 9000 em 0.0.0.0 com TLS terminando no nginx
      - "127.0.0.1:9000:9000"
      # HTTPS direto (acesso emergencial, IP-only)
      - "9443:9443"
      # Edge tunnel server (recebe outbound de Edge Agents)
      - "8000:8000"
    volumes:
      # Socket Docker. RW e necessario para a maioria das operacoes
      # (criar/destruir containers, networks, volumes, stacks).
      # Read-only quebra UI - mantenha RW e proteja via auth + rede.
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    networks:
      - proxy

volumes:
  portainer_data:
    driver: local

networks:
  proxy:
    external: true

Suba:

docker compose up -d
docker compose logs -f portainer

Verifique:

docker ps --filter name=portainer
curl -k https://localhost:9443/api/status
curl http://127.0.0.1:9000/api/status

Notas de seguranca da exposicao

  • docker.sock read-only quebra muita coisa (qualquer POST ao daemon). Documente o tradeoff e proteja o Portainer com auth forte + rede restrita.
  • Nao publique 9000 em 0.0.0.0 em producao — apenas atras de proxy TLS.
  • 9443 pode ficar exposto se voce restringir por firewall (allowlist da rede confiavel).
  • 8000 so precisa estar publico se voce usa Edge Agents externos.

5. Primeiro acesso

Abra https://<IP-do-servidor>:9443 (ignore o aviso de cert self-signed).

Voce vera o bootstrap wizard:

  1. Crie o admin inicial: username (evite admin puro) + senha de 12 caracteres minimo, com letras, numeros e simbolo.
  2. Atencao ao timeout: se voce demorar mais de 5 minutos entre subir o container e abrir essa tela, o bootstrap expira por seguranca e voce precisa reiniciar:
    docker restart portainer
  3. Apos criar o admin, escolha o environment inicial: “Get Started — Manage the local Docker environment” (usa o socket montado).

Voce cai no dashboard com 1 environment chamado local.


6. Reverse proxy com nginx-proxy

Crie /opt/docker/nginx/conf.d/portainer.example.com.conf:

# upstream apontando para o container Portainer na rede proxy
upstream portainer_backend {
    server portainer:9000;
}

server {
    listen 80;
    server_name portainer.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name portainer.example.com;

    ssl_certificate     /etc/letsencrypt/live/portainer.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/portainer.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    # Allowlist da rede confiavel - ajuste para sua faixa
    # allow 10.8.0.0/24;
    # deny all;

    client_max_body_size 100M;

    location / {
        proxy_pass http://portainer_backend;
        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;

        # WebSocket upgrade - critico para terminal web (exec)
        # e para logs em tempo real
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeouts longos para SSE / streaming de logs
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;
    }

    # Endpoint da API de Edge Agents (se for usar Edge externamente,
    # exponha tambem o 8000 - pode ser outro vhost edge.example.com)
}

Recarregue:

docker exec nginx-proxy nginx -t
docker exec nginx-proxy nginx -s reload

HTTP interno + TLS no nginx (recomendado) vs HTTPS duplo

  • Recomendado: nginx termina TLS publico, fala HTTP :9000 com Portainer pela rede proxy. Menos overhead, certs gerenciados num lugar so.
  • HTTPS duplo (nginx -> :9443 do Portainer com cert self-signed): adiciona complexidade, exige proxy_ssl_verify off, sem ganho real ja que o trafego e interno a network Docker.

7. Autenticacao e SSO via Keycloak

Configure o Portainer para delegar login ao Keycloak.

7.1 Criar client no Keycloak

No realm desejado (ex.: meu-realm), Clients > Create client:

  • Client type: OpenID Connect
  • Client ID: portainer
  • Client authentication: ON (confidential)
  • Standard flow: ON
  • Valid redirect URIs: https://portainer.example.com/*
  • Web origins: https://portainer.example.com

Em Credentials, copie o Client secret.

Opcional: crie um grupo portainer-users e mapeie atributo preferred_username (ja vem por padrao).

7.2 Configurar OAuth no Portainer

Settings > Authentication > OAuth > Custom:

CampoValor
Client IDportainer
Client secret(do Keycloak)
Authorization URLhttps://auth.example.com/realms/meu-realm/protocol/openid-connect/auth
Access token URLhttps://auth.example.com/realms/meu-realm/protocol/openid-connect/token
Resource URL (userinfo)https://auth.example.com/realms/meu-realm/protocol/openid-connect/userinfo
Redirect URLhttps://portainer.example.com
Logout URL (opcional)https://auth.example.com/realms/meu-realm/protocol/openid-connect/logout
Scopesopenid profile email
User identifierpreferred_username
Auto user provisioningON (cria conta Portainer no primeiro login)
Default team(criar team Devs antes e selecionar)

Salve. Faca logout, na tela de login aparece “Login with OAuth”. Teste com um usuario Keycloak.

7.3 Mapeamento automatico de team (BE feature)

Em CE, todo usuario novo cai no Default team. Para mapear claims do JWT em teams especificos voce precisa do BE. Workaround em CE: criar usuarios manualmente e atribuir teams.


8. Environments (multiplos hosts)

Voce tem 3 opcoes para adicionar um segundo host Docker.

Opcao A — Docker API via TCP + TLS mutuo (desencorajado em internet)

Exige expor dockerd -H tcp://0.0.0.0:2376 com certs gerados (CA + server + client). Funciona mas:

  • Qualquer falha de cert = acesso root no host.
  • Nao expoe nada extra (logs em arquivo, stats, etc) que o Agent oferece.
  • Use somente em LAN privada ou VPN, nunca exposto direto na internet.

Opcao B — Portainer Agent (recomendado para LAN/VPN)

No host remoto:

docker run -d \
  --name portainer_agent \
  --restart=always \
  -p 9001:9001 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  portainer/agent:latest

Para Swarm, adicione -e AGENT_CLUSTER_ADDR=tasks.agent e use stack mode com replicas global. O AGENT_SECRET pode ser configurado nos dois lados (server e agent) para mutual auth basico:

-e AGENT_SECRET=<random-32-chars>

No Portainer Server, defina o mesmo AGENT_SECRET via env var no compose.

No Portainer UI: Environments > Add environment > Docker Standalone > Agent:

  • Name: internal-server
  • Environment address: internal-server.lan:9001 (ou IP via rede privada/VPN)
  • TLS: o Agent gera cert self-signed; marque “skip TLS verification” ou faca pin do cert.

Conectividade: Portainer Server precisa alcancar o Agent (inbound no Agent). Em redes privadas com VPN isso e trivial.

Opcao C — Edge Agent (recomendado para hosts NAT/CGNAT)

Edge Agent inverte o fluxo: o Agent faz conexao outbound para :8000 do Portainer Server. Resolve NAT, CGNAT, hosts moveis.

No Portainer: Environments > Add > Docker Standalone > Edge Agent > Standard (ou Async para conexoes intermitentes).

Voce recebe um snippet do tipo:

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  -v portainer_agent_data:/data \
  --restart always \
  -e EDGE=1 \
  -e EDGE_ID=<UUID-gerado> \
  -e EDGE_KEY=<base64-com-server-URL+tunnel-port+endpoint-ID> \
  -e EDGE_INSECURE_POLL=0 \
  --name portainer_edge_agent \
  portainer/agent:latest

EDGE_KEY codifica em base64: URL do Portainer, porta do tunnel (8000), endpoint ID, poll frequency. O Agent registra-se sozinho ao subir.

Async mode (BE/CE 2.20+): util quando o host fica offline com frequencia — comandos ficam enfileirados ate o Agent reconectar.

ModoDirecao conexaoPorta expostaCaso de uso
API TLSServer -> Daemon2376 (host)LAN trusted
AgentServer -> Agent9001 (host)LAN/VPN
Edge AgentAgent -> Server8000 (server)NAT, mobile

9. Stacks (docker-compose gerenciado)

Stacks sao a feature mais util do Portainer. Voce gerencia compose files via UI mantendo deploy idempotente.

9.1 Criar stack via Web Editor

Stacks > Add stack:

  • Name: meu-app (lowercase, sem espacos — vira prefixo dos containers)
  • Build method: Web editor
  • Cole o compose:
services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - proxy

volumes:
  redis_data:

networks:
  proxy:
    external: true
  • Environment variables: adicione chave/valor ou faca upload de .env.
  • Access control: defina team/user owners.
  • Click Deploy the stack.

9.2 Update preservando volumes

Volumes nomeados sobrevivem a redeploys. Stacks > <nome> > Editor > altera o YAML > Update the stack. Marque:

  • Re-pull image se mudou tag/digest.
  • Prune services para remover services que sumiram do compose.

Containers sao recriados; volumes nomeados ficam intactos. Bind mounts apontam para paths do host — tambem persistem.

9.3 Stacks a partir de Git (GitOps)

Stacks > Add stack > Repository:

  • Repository URL: https://git.example.com/usuario/meus-stacks.git (HTTPS ou SSH com deploy key)
  • Authentication: usuario + token do servidor Git (ou deploy key SSH)
  • Repository reference: refs/heads/main
  • Compose path: apps/meu-app/docker-compose.yaml
  • Additional paths: apps/meu-app/docker-compose.override.yaml (opcional)
  • GitOps updates: ON
    • Mechanism: Polling a cada 60s, ou Webhook (gera URL /api/stacks/webhooks/<uuid>)
    • Re-pull image: ON se voce usa tag flutuante latest
    • Force redeployment: ON se quer sobrescrever drift local

Fluxo: voce edita compose no repositorio Git -> Portainer detecta hash novo -> re-deploy automatico. Volumes preservados.


10. Templates

App Templates sao receitas pre-feitas (Wordpress, Nextcloud, etc) disponiveis em App Templates.

Templates customizados

App Templates > Custom Templates > Add:

  • Title: Postgres 17 + PgAdmin
  • Description: …
  • Compose file: cole o YAML usando placeholders ${VAR}
  • Variables: defina cada uma com label, descricao e default:
[
  {
    "name": "POSTGRES_PASSWORD",
    "label": "Senha do superuser",
    "description": "Min 16 chars",
    "default": "CHANGE_ME_STRONG_PASSWORD"
  },
  {
    "name": "DATA_PATH",
    "label": "Bind path no host",
    "default": "/srv/pg"
  }
]

Voce tambem pode hospedar templates.json em URL publica e apontar Settings > App templates > URL.


11. Container management

Operacoes do dia-a-dia em Containers > <container>:

  • Stats: graficos de CPU / memoria / IO disco / IO rede em tempo real (SSE).
  • Logs: tail real-time com filtro por texto, timestamps, “Auto-refresh”, download.
  • Console / Exec: terminal web (shell /bin/sh ou /bin/bash) — exige WebSocket no proxy.
  • Inspect: JSON cru do docker inspect.
  • Attach: anexa ao stdout/stderr do PID 1.
  • Duplicate / Edit: clona o container; “Edit” abre form para alterar imagem/ports/env/volumes e cria container novo (Portainer destroi o antigo). Util para mudar tag de imagem rapido.
  • Recreate: mesma config, container fresco — equivalente a docker rm && docker run.
  • Health: se o container tem HEALTHCHECK, mostra status e ultimas saidas.

12. Networks, Volumes e Images

Networks

Networks lista todas. Voce pode criar bridge/overlay, definir IPAM (subnet, gateway), driver options. Inspecionar containers conectados.

Volumes

Volumes mostra:

  • Driver, mount point real no host, stack/container dono.
  • Browse (CE permite navegar conteudo de volumes locais — util para verificar bind mounts).
  • Remove unused (prune) com confirmacao.

Images

Images lista todas com tamanho real (layers), tags, “in use” flag.

  • Pull: novo docker pull com credenciais de registry ja salvas.
  • Build: build de Dockerfile via UI (a partir de Git ou web editor).
  • Push: requer registry configurado.
  • Prune dangling: limpa imagens orfas com seguranca.

13. Registries

Settings > Registries > Add registry:

  • Custom / Docker Hub / Quay / Azure / ECR / Gitlab.

Registry privado (ex.: Nexus, Harbor)

  • Name: registry-privado
  • URL: registry.example.com
  • Authentication: ON, user + password do registry
  • Apos salvar, o registry aparece em Images > Pull como opcao e em Stacks (Portainer injeta creds no compose para fazer pull).

Container Registry de servidor Git (Gitea, GitLab, etc.)

  • URL: git.example.com (ou subdominio especifico se configurado)
  • Token gerado nas configuracoes do servidor Git (Settings > Applications > Generate Token com scope read:package/write:package).

Docker Hub

  • URL: vazio (default index.docker.io)
  • Usuario + Access Token (nao senha).

Webhooks de image update

Por registry, voce pode habilitar webhook que dispara repull quando uma tag muda. CE: feature presente em conjunto com Force redeploy em stacks Git.


14. Webhooks de servico

Util para CI/CD: ao final do build, o pipeline chama uma URL e Portainer repuxa imagem e recria container/stack.

Container webhook

Containers > <container> > Duplicate/Edit > Webhook: ON. Gera:

https://portainer.example.com/api/webhooks/<uuid>

Chamada via POST (qualquer body):

curl -X POST https://portainer.example.com/api/webhooks/<uuid>

Portainer faz pull da imagem (com a mesma tag) e recria o container preservando config.

Stack webhook

Em stacks com GitOps updates > Webhook, voce recebe URL similar. POST nela = git pull + docker compose up -d.

Integre em GitHub Actions, GitLab CI, Gitea Actions, Drone, Jenkins, ou direto em post-receive hook.


15. RBAC e Teams

Users > Teams > Add team: ex. Devs, Ops.

Users > Add user: vincule a teams.

Roles por environment (CE)

Em Environments > <env> > Manage access:

  • Environment administrator: tudo no environment.
  • Helpdesk: read + logs + stats, sem operacoes destrutivas.
  • Standard user: opera recursos que tem acesso (Stacks/Volumes/etc atribuidos).
  • Read-only user: so visualiza.

Em CE, o RBAC e por environment. BE adiciona granularidade por recurso (este stack X so Devs editam, mas Helpdesk pode ver logs).

Limitacoes CE relevantes:

  • Sem RBAC granular por stack/container.
  • Sem mapping de teams a partir de claims OAuth/SAML.
  • Audit log basico (apenas auth events).

16. GitOps-style stack (workflow recomendado)

Fluxo recomendado:

  1. Repositorio Git meus-stacks com estrutura:
    apps/
      meu-app/
        docker-compose.yaml
        stack.env
  2. Stack no Portainer com source = Git, polling 60s, Re-pull image: ON.
  3. Branch protection: PR review em main.
  4. Voce edita compose -> push -> Portainer reaplica em <= 60s.

Comparacao com outras abordagens

FerramentaGranularidadeCasa bem com
Portainer GitOpsStack-level (compose)Ambientes small/medium, multi-host
WatchtowerImage-level (so pull novas tags)Apps simples sem mudanca de YAML
Argo CD / FluxK8s manifestsProducao K8s
KomodoBuild + deploy via GitPipelines complexos

Portainer cobre 95% do que voce precisa em ambientes Docker pequenos a medios sem migrar para K8s.


17. Backup e restore

Portainer guarda toda config em SQLite no volume portainer_data (users, stacks, registries, env, settings, certs).

Backup manual

Settings > Backup Portainer:

  • Defina password (criptografa o tarball).
  • Download portainer-backup_<timestamp>.tar.gz.
  • Conteudo: DB + certs + chaves.
  • NAO inclui: imagens, volumes de dados das apps, containers em si.

Voce continua precisando de backup separado para postgres, object storage, etc.

Backup automatizado (recomendado)

# Snapshot do volume Docker
docker run --rm \
  -v portainer_portainer_data:/data \
  -v /srv/backups:/backup \
  alpine tar czf /backup/portainer-$(date +%F).tgz -C /data .

Agende em cron + envie pra B2/S3 com restic ou rclone.

Restore

  1. Suba uma instalacao limpa do Portainer.
  2. No primeiro acesso, escolha Restore Portainer from backup.
  3. Upload do tarball + password.
  4. Portainer reinicia carregando o backup.

Alternativa offline:

docker stop portainer
docker run --rm \
  -v portainer_portainer_data:/data \
  -v /srv/backups:/backup \
  alpine tar xzf /backup/portainer-YYYY-MM-DD.tgz -C /data
docker start portainer

18. Security hardening

Checklist:

  • Senha admin forte (16+ chars, gerador). Trocar a default imediatamente.
  • Telemetry off: Settings > General > Allow collection of anonymous statistics: OFF.
  • TLS no Agent: AGENT_SECRET no Server + Agent, sem --insecure-skip-tls-verify.
  • Docker socket: idealmente mediado por socket-proxy (tecnativa/docker-socket-proxy) limitando endpoints:
    socket-proxy:
      image: tecnativa/docker-socket-proxy
      environment:
        CONTAINERS: 1
        IMAGES: 1
        NETWORKS: 1
        VOLUMES: 1
        SERVICES: 1
        TASKS: 1
        POST: 1
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock:ro
    E Portainer aponta para tcp://socket-proxy:2375 ao inves do socket cru. Custo: voce perde algumas features (logs SSE podem instabilizar).
  • Firewall no servidor: feche 9000, 9443 e 8000 no ufw/nftables, libere so:
    • Rede confiavel (VPN/admin)
    • :8000 publico so se voce usa Edge Agents externos
  • Audit log: Settings > Logs (CE registra login/logout, criacao de usuarios). Exporte periodicamente.
  • 2FA: My account > Two-factor authentication > Enable (TOTP). Disponivel em CE.
  • Disable public registry: se nao usa Docker Hub publico, remova das opcoes em Settings > Registries.

19. Troubleshooting

”Failed to verify TLS certificate” no Agent

O Agent gera cert self-signed novo a cada subida. Solucoes:

  • No add environment: marque Skip TLS verification.
  • Ou fixe o cert: copie /data/certs/cert.pem do Agent e adicione em TLS CA certificate no Server.
  • Verifique se hostname do environment bate com SAN do cert (use IP ou hostname consistente).

”Cannot connect to the Docker daemon”

Container Portainer sem acesso ao socket. Confirme:

docker inspect portainer | grep -A2 Mounts
# deve mostrar /var/run/docker.sock
ls -l /var/run/docker.sock
# deve ser srw-rw---- root:docker

Se o socket nao existe, Docker daemon nao esta rodando. Se existe mas Portainer reclama, problema de permissao SELinux/AppArmor: tente --privileged no Portainer ou ajuste politica.

Stack stuck em “Deploying”

Compose com depends_on: condition: service_healthy cujo healthcheck nunca passa. Portainer espera o stack chegar a running antes de marcar “Deployed”. Verifique:

docker compose -p <stack-name> ps
docker logs <container-com-healthcheck>

Conserte o healthcheck ou remova a condicao service_healthy.

Terminal web (exec) nao abre / fica em branco

Falta WebSocket no proxy. No nginx confirme:

proxy_http_version 1.1;
proxy_set_header Upgrade    $http_upgrade;
proxy_set_header Connection "upgrade";

E que nao ha buffering hostil:

proxy_buffering off;

Cloudflare na frente: ative WebSocket no painel CF + use Proxied ou DNS only dependendo da licenca.

OAuth: “redirect_uri_mismatch”

Keycloak rejeita callback. Conferir:

  • Valid redirect URIs no client Keycloak inclui exatamente https://portainer.example.com/*.
  • Redirect URL no Portainer e exatamente https://portainer.example.com (sem trailing slash, sem /auth).
  • Se voce acessa as vezes por IP, as vezes por dominio, fixe tudo no dominio.

”Port already allocated” ao subir Portainer

Algum container ja usa 9000/9443/8000. Mude binding:

ports:
  - "127.0.0.1:9000:9000"
  - "9543:9443"
  - "8443:8000"

E ajuste configs Edge/proxy.

Edge Agent nao conecta

  • :8000 do servidor publicamente alcancavel? nc -vz portainer.example.com 8000 do host do Edge.
  • Firewall do host Edge bloqueando outbound HTTPS? Edge Agent fala HTTPS via tunnel.
  • EDGE_KEY correta? Regenere no Portainer e refaca o docker run.

Storage cheio apos meses

docker exec portainer du -sh /data
# normalmente <500MB; se passar de 5GB tem algo errado

Logs internos podem inflar. Limpe:

docker exec portainer find /data/log -name "*.log" -mtime +30 -delete

20. Referencias


Apendice — quick reference de portas

PortaServicoDirecaoNotas
9000Portainer UI HTTPinbound (server)Atras de TLS proxy
9443Portainer UI HTTPSinbound (server)Self-signed default
8000Edge tunnelinbound (server)Recebe conexoes outbound de Edge Agents
9001Portainer Agentinbound (agent host)Server inicia conexao
2376Docker API TLSinbound (host)Alternativa nao-recomendada