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)
| Recurso | CE (free) | BE (paid) |
|---|---|---|
| Containers / Images / Volumes / Networks | Sim | Sim |
| Stacks (compose) | Sim | Sim |
| Multi-environment (Agent / Edge) | Sim | Sim |
| OAuth / OIDC | Sim | Sim |
| RBAC granular por recurso | Limitado (env-level) | Sim (per-resource) |
| Activity logs / Audit logs | Basico | Completo |
| Edge Compute (jobs, configs) | Limitado | Completo |
| GitOps por stack | Sim | Sim |
| Suporte oficial | Comunidade | SLA |
| Custo | Gratis | Por node/mes |
Para 1-3 nos, CE basta. Audit log avancado e RBAC fino sao os principais diferenciais BE.
Comparacao com alternativas
| Ferramenta | Forca | Limitacao |
|---|---|---|
| Portainer CE | Stacks GitOps, multi-host, OAuth, registries, web terminal | UI as vezes lenta com muitos containers |
| Yacht | UI minimalista, leve | Projeto em alpha, pouco mantido |
| Dockge | Foco em compose, hot reload de YAML, mais leve | Single-host, sem RBAC, sem registries |
| Lazydocker | TUI rapida, sem servidor | Local-only, sem mobile |
| Komodo (ex-Monitor) | GitOps-first, builds, alertas | Curva 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| RegistryPontos 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
:8000do 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
/datado 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 proxy4. 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: trueSuba:
docker compose up -d
docker compose logs -f portainerVerifique:
docker ps --filter name=portainer
curl -k https://localhost:9443/api/status
curl http://127.0.0.1:9000/api/statusNotas de seguranca da exposicao
docker.sockread-only quebra muita coisa (qualquerPOSTao daemon). Documente o tradeoff e proteja o Portainer com auth forte + rede restrita.- Nao publique
9000em0.0.0.0em producao — apenas atras de proxy TLS. 9443pode ficar exposto se voce restringir por firewall (allowlist da rede confiavel).8000so 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:
- Crie o admin inicial: username (evite
adminpuro) + senha de 12 caracteres minimo, com letras, numeros e simbolo. - 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 - 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 reloadHTTP interno + TLS no nginx (recomendado) vs HTTPS duplo
- Recomendado: nginx termina TLS publico, fala HTTP
:9000com Portainer pela redeproxy. Menos overhead, certs gerenciados num lugar so. - HTTPS duplo (nginx ->
:9443do Portainer com cert self-signed): adiciona complexidade, exigeproxy_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:
| Campo | Valor |
|---|---|
| Client ID | portainer |
| Client secret | (do Keycloak) |
| Authorization URL | https://auth.example.com/realms/meu-realm/protocol/openid-connect/auth |
| Access token URL | https://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 URL | https://portainer.example.com |
| Logout URL (opcional) | https://auth.example.com/realms/meu-realm/protocol/openid-connect/logout |
| Scopes | openid profile email |
| User identifier | preferred_username |
| Auto user provisioning | ON (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:latestPara 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:latestEDGE_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.
| Modo | Direcao conexao | Porta exposta | Caso de uso |
|---|---|---|---|
| API TLS | Server -> Daemon | 2376 (host) | LAN trusted |
| Agent | Server -> Agent | 9001 (host) | LAN/VPN |
| Edge Agent | Agent -> Server | 8000 (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:
Pollinga cada60s, ouWebhook(gera URL/api/stacks/webhooks/<uuid>) - Re-pull image: ON se voce usa tag flutuante
latest - Force redeployment: ON se quer sobrescrever drift local
- Mechanism:
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/shou/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 pullcom 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 > Pullcomo 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 Tokencom scoperead: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:
- Repositorio Git
meus-stackscom estrutura:apps/ meu-app/ docker-compose.yaml stack.env - Stack no Portainer com source = Git, polling 60s,
Re-pull image: ON. - Branch protection: PR review em
main. - Voce edita compose -> push -> Portainer reaplica em <= 60s.
Comparacao com outras abordagens
| Ferramenta | Granularidade | Casa bem com |
|---|---|---|
| Portainer GitOps | Stack-level (compose) | Ambientes small/medium, multi-host |
| Watchtower | Image-level (so pull novas tags) | Apps simples sem mudanca de YAML |
| Argo CD / Flux | K8s manifests | Producao K8s |
| Komodo | Build + deploy via Git | Pipelines 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
- Suba uma instalacao limpa do Portainer.
- No primeiro acesso, escolha Restore Portainer from backup.
- Upload do tarball + password.
- 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 portainer18. 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_SECRETno Server + Agent, sem--insecure-skip-tls-verify. - Docker socket: idealmente mediado por socket-proxy (
tecnativa/docker-socket-proxy) limitando endpoints:
E Portainer aponta parasocket-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:rotcp://socket-proxy:2375ao inves do socket cru. Custo: voce perde algumas features (logs SSE podem instabilizar). - Firewall no servidor: feche
9000,9443e8000noufw/nftables, libere so:- Rede confiavel (VPN/admin)
:8000publico 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.pemdo Agent e adicione emTLS CA certificateno 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:dockerSe 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 URIsno client Keycloak inclui exatamentehttps://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
:8000do servidor publicamente alcancavel?nc -vz portainer.example.com 8000do host do Edge.- Firewall do host Edge bloqueando outbound HTTPS? Edge Agent fala HTTPS via tunnel.
EDGE_KEYcorreta? Regenere no Portainer e refaca odocker run.
Storage cheio apos meses
docker exec portainer du -sh /data
# normalmente <500MB; se passar de 5GB tem algo erradoLogs internos podem inflar. Limpe:
docker exec portainer find /data/log -name "*.log" -mtime +30 -delete20. Referencias
- Documentacao oficial: https://docs.portainer.io/
- Install CE Server (Linux): https://docs.portainer.io/start/install-ce/server/docker/linux
- Agent setup: https://docs.portainer.io/admin/environments/add/docker/agent
- Edge Agent: https://docs.portainer.io/admin/environments/add/edge
- OAuth (Keycloak): https://docs.portainer.io/admin/settings/authentication/oauth
- Stacks: https://docs.portainer.io/user/docker/stacks/add
- GitOps updates: https://docs.portainer.io/user/docker/stacks/gitops
- Custom templates: https://docs.portainer.io/admin/templates/custom
- Backup/restore: https://docs.portainer.io/admin/settings/backup
- API reference: https://docs.portainer.io/api/docs
- Comparativos: https://github.com/SelfhostedPro/Yacht, https://github.com/louislam/dockge
- Socket proxy: https://github.com/Tecnativa/docker-socket-proxy
- Repositorio Portainer: https://github.com/portainer/portainer
Apendice — quick reference de portas
| Porta | Servico | Direcao | Notas |
|---|---|---|---|
| 9000 | Portainer UI HTTP | inbound (server) | Atras de TLS proxy |
| 9443 | Portainer UI HTTPS | inbound (server) | Self-signed default |
| 8000 | Edge tunnel | inbound (server) | Recebe conexoes outbound de Edge Agents |
| 9001 | Portainer Agent | inbound (agent host) | Server inicia conexao |
| 2376 | Docker API TLS | inbound (host) | Alternativa nao-recomendada |