pgAdmin¶

O pgAdmin é a interface web utilizada para administrar bancos PostgreSQL.

Nesta VPS, ele está conectado às redes proxy e n8n-net, permitindo acesso pelo Traefik e comunicação interna com o PostgreSQL do n8n.

Informações desta VPS¶

Item	Valor
Stack	`/opt/stacks/pgadmin/compose.yml`
Serviço Compose	`pgadmin`
Container	`pgadmin`
Imagem configurada	`dpage/pgadmin4:latest`
Versão instalada	`9.9`
Versão mais recente verificada	`9.16`
Domínio	`https://pgadmin.cloud.hometecseg.com`
Porta interna usada	`80`
Portas expostas pela imagem	`80` e `443`
Rede externa	`proxy`
Rede do n8n	`n8n-net`
Volume	`pgadmin_pgadmin-data`
Diretório no container	`/var/lib/pgadmin`
E-mail administrativo	`admin@cloud.hometecseg.com`
Healthcheck	Não configurado

Credenciais

A senha administrativa está no arquivo .env. Ela não deve ser escrita nesta documentação, enviada em mensagens ou publicada em repositórios.

Estado¶

Ver o estado do serviço¶

docker compose -f /opt/stacks/pgadmin/compose.yml ps -a pgadmin

Ver o container em execução¶

docker ps --filter name=pgadmin

Ver o estado detalhado¶

docker inspect pgadmin \
  --format 'Status={{.State.Status}} ExitCode={{.State.ExitCode}} StartedAt={{.State.StartedAt}} FinishedAt={{.State.FinishedAt}} OOMKilled={{.State.OOMKilled}}'

Iniciar e parar¶

Iniciar o pgAdmin¶

docker compose -f /opt/stacks/pgadmin/compose.yml start pgadmin

Caso o container não exista:

docker compose -f /opt/stacks/pgadmin/compose.yml up -d pgadmin

Parar o pgAdmin¶

docker compose -f /opt/stacks/pgadmin/compose.yml stop pgadmin

Reiniciar o pgAdmin¶

docker compose -f /opt/stacks/pgadmin/compose.yml restart pgadmin

Recriar o container¶

docker compose -f /opt/stacks/pgadmin/compose.yml up -d --force-recreate pgadmin

Confirmar o estado¶

docker compose -f /opt/stacks/pgadmin/compose.yml ps pgadmin

Acesso¶

Endereço:

https://pgadmin.cloud.hometecseg.com

Usuário administrativo:

admin@cloud.hometecseg.com

Testar o domínio¶

curl -I https://pgadmin.cloud.hometecseg.com

Verificar o DNS¶

getent hosts pgadmin.cloud.hometecseg.com

Ver detalhes da conexão¶

curl -v https://pgadmin.cloud.hometecseg.com

Logs¶

Ver os últimos 100 registros¶

docker logs pgadmin --tail 100

Acompanhar os logs¶

docker logs -f pgadmin

Procurar erros¶

docker logs pgadmin 2>&1 \
  | grep -Ei "error|fatal|panic|exception"

Procurar avisos¶

docker logs pgadmin 2>&1 \
  | grep -Ei "warn|warning"

Versão¶

Ver a versão instalada¶

docker exec pgadmin sh -c \
"cd /pgadmin4 && python3 -c 'import version; print(version.APP_VERSION)'"

Resultado registrado:

9.9

Ver a imagem configurada¶

grep -n "dpage/pgadmin4" /opt/stacks/pgadmin/compose.yml

Ver a imagem usada pelo container¶

docker inspect pgadmin \
  --format '{{.Config.Image}}'

Ver o identificador da imagem usada¶

docker inspect pgadmin \
  --format '{{.Image}}'

Versão mais recente disponível¶

Estado verificado ao criar esta documentação:

Item	Versão
Instalada	`9.9`
Mais recente	`9.16`

Existe uma atualização disponível.

Informação temporal

O número da versão mais recente muda. Verifique sempre a página oficial do pgAdmin antes de atualizar.

Verificar atualização disponível¶

Baixar a imagem mais recente¶

docker pull dpage/pgadmin4:latest

Esse comando baixa a imagem, mas não recria o container.

Ver o identificador da imagem baixada¶

docker image inspect dpage/pgadmin4:latest \
  --format '{{.Id}}'

Comparar com a imagem do container¶

CONTAINER_IMAGE="$(docker inspect pgadmin --format '{{.Image}}')" &&
LATEST_IMAGE="$(docker image inspect dpage/pgadmin4:latest --format '{{.Id}}')" &&
if [ "$CONTAINER_IMAGE" = "$LATEST_IMAGE" ]; then
  echo "pgAdmin já utiliza a imagem mais recente baixada."
else
  echo "Existe uma imagem diferente da usada pelo container."
fi

Fixar uma versão¶

Em vez de usar:

image: dpage/pgadmin4:latest

é possível fixar:

image: dpage/pgadmin4:9.16

Isso evita atualizações inesperadas.

Tag fixa

Fixar uma versão melhora previsibilidade, mas exige atualização manual quando novas correções forem publicadas.

Backup¶

Criar diretório¶

mkdir -p /opt/backups/pgadmin

Criar backup do Compose¶

cp /opt/stacks/pgadmin/compose.yml \
  /opt/backups/pgadmin/compose-$(date +%Y%m%d-%H%M%S).yml

Criar backup do `.env`¶

cp /opt/stacks/pgadmin/.env \
  /opt/backups/pgadmin/env-$(date +%Y%m%d-%H%M%S).bak

Arquivo sensível

O backup do .env contém credenciais. Restrinja as permissões desse arquivo.

Ajustar permissões do backup do `.env`¶

chmod 600 /opt/backups/pgadmin/env-*.bak

Parar o pgAdmin¶

docker compose -f /opt/stacks/pgadmin/compose.yml stop pgadmin

Criar backup do volume¶

docker run --rm \
  -v pgadmin_pgadmin-data:/source:ro \
  -v /opt/backups/pgadmin:/backup \
  alpine \
  tar -czf "/backup/pgadmin-data-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /source .

Iniciar novamente¶

docker compose -f /opt/stacks/pgadmin/compose.yml start pgadmin

Listar backups¶

ls -lh /opt/backups/pgadmin

Atualização manual¶

Criar backup antes da atualização¶

mkdir -p /opt/backups/pgadmin

docker compose -f /opt/stacks/pgadmin/compose.yml stop pgadmin

docker run --rm \
  -v pgadmin_pgadmin-data:/source:ro \
  -v /opt/backups/pgadmin:/backup \
  alpine \
  tar -czf "/backup/pgadmin-data-pre-update-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /source .

Validar o Compose¶

docker compose -f /opt/stacks/pgadmin/compose.yml config

Baixar a imagem¶

docker compose -f /opt/stacks/pgadmin/compose.yml pull pgadmin

Recriar o serviço¶

docker compose -f /opt/stacks/pgadmin/compose.yml up -d pgadmin

Verificar o estado¶

docker compose -f /opt/stacks/pgadmin/compose.yml ps pgadmin

Verificar os logs¶

docker logs pgadmin --tail 100

Confirmar a versão¶

docker exec pgadmin sh -c \
"cd /pgadmin4 && python3 -c 'import version; print(version.APP_VERSION)'"

Testar o domínio¶

curl -I https://pgadmin.cloud.hometecseg.com

Atualização pelo script¶

Existe um script dedicado:

/usr/local/bin/update_pgadmin.sh

Ele será analisado posteriormente na página de scripts.

Visualizar o conteúdo¶

sed -n '1,260p' /usr/local/bin/update_pgadmin.sh

Verificar permissões¶

ls -l /usr/local/bin/update_pgadmin.sh

Revisão necessária

Antes de executá-lo, confirme se o script cria backup, valida o Compose, verifica a versão e preserva o estado do modo econômico.

Volume persistente¶

Ver as montagens¶

docker inspect pgadmin \
  --format '{{range .Mounts}}{{println .Type "|" .Name "|" .Source "|" .Destination}}{{end}}'

Inspecionar o volume¶

docker volume inspect pgadmin_pgadmin-data

Ver espaço utilizado¶

du -sh /var/lib/docker/volumes/pgadmin_pgadmin-data/_data

Listar arquivos persistentes¶

ls -lah /var/lib/docker/volumes/pgadmin_pgadmin-data/_data

Não editar diretamente

Não altere manualmente os arquivos internos do volume enquanto o pgAdmin estiver ativo.

Redes¶

Ver as redes do container¶

docker inspect pgadmin \
  --format '{{json .NetworkSettings.Networks}}'

Verificar a rede proxy¶

docker network inspect proxy

Verificar a rede n8n¶

docker network inspect n8n-net

O pgAdmin precisa da rede n8n-net para alcançar o PostgreSQL pelo nome interno do serviço.

Conectar ao PostgreSQL do n8n¶

No pgAdmin, cadastrar um servidor com:

Campo	Valor
Nome	`PostgreSQL n8n`
Host	`postgres`
Porta	`5432`
Banco	`n8n`
Usuário	`n8n`

A senha deve ser obtida no arquivo .env da stack do n8n.

Não expor a senha

Não copie a senha para documentação, prints ou mensagens.

Porta interna¶

A imagem expõe:

80/tcp
443/tcp

Nesta VPS, o Traefik encaminha para:

Confirmar as portas expostas¶

docker inspect pgadmin \
  --format '{{json .Config.ExposedPorts}}'

Confirmar a porta configurada no Traefik¶

docker inspect pgadmin \
  --format '{{json .Config.Labels}}' \
  | grep loadbalancer

Healthcheck¶

Atualmente não há healthcheck configurado:

Healthcheck=null

Verificar diretamente¶

docker inspect pgadmin \
  --format '{{json .Config.Healthcheck}}'

Exemplo de healthcheck futuro¶

healthcheck:
  test: ["CMD", "wget", "--spider", "-q", "http://localhost:80/misc/ping"]
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 60s

Configuração sugerida

Esse healthcheck ainda não faz parte do Compose atual e deve ser testado antes da adoção.

Traefik¶

Ver as labels¶

docker inspect pgadmin \
  --format '{{json .Config.Labels}}'

Ver logs do Traefik¶

docker logs reverse-proxy-traefik-1 --tail 100

Troubleshooting¶

pgAdmin não inicia¶

docker compose -f /opt/stacks/pgadmin/compose.yml ps -a

docker logs pgadmin --tail 200

docker compose -f /opt/stacks/pgadmin/compose.yml config

Erro de permissão no volume¶

ls -lah /var/lib/docker/volumes/pgadmin_pgadmin-data/_data

docker logs pgadmin 2>&1 \
  | grep -Ei "permission|denied"

Erro 404¶

getent hosts pgadmin.cloud.hometecseg.com

docker inspect pgadmin \
  --format '{{json .Config.Labels}}'

docker logs reverse-proxy-traefik-1 --tail 100

Erro 502 ou Gateway Timeout¶

docker compose -f /opt/stacks/pgadmin/compose.yml ps pgadmin

docker network inspect proxy

docker logs pgadmin --tail 100

docker logs reverse-proxy-traefik-1 --tail 100

A porta interna esperada é:

pgAdmin não conecta ao PostgreSQL¶

Verificar a rede:

docker network inspect n8n-net

Verificar se o PostgreSQL está ativo:

docker compose -f /opt/stacks/n8n/compose.yml ps postgres

Testar resolução de nome dentro do pgAdmin:

docker exec pgadmin getent hosts postgres

Testar a porta:

docker exec pgadmin sh -c \
'python3 -c "import socket; s=socket.create_connection((\"postgres\",5432),5); print(\"Conexão TCP OK\"); s.close()"'

Confirmar apenas o e-mail configurado:

grep '^PGADMIN_DEFAULT_EMAIL=' /opt/stacks/pgadmin/.env

Não exiba a senha.

Interface lenta¶

docker stats pgadmin

du -sh /var/lib/docker/volumes/pgadmin_pgadmin-data/_data

docker logs pgadmin --tail 200

Boas práticas¶

Fixar uma versão em vez de usar latest.
Fazer backup do volume antes de atualizar.
Proteger o arquivo .env.
Não expor diretamente as portas 80 ou 443.
Usar o Traefik para acesso externo.
Não remover o volume pgadmin_pgadmin-data.
Não editar diretamente os arquivos persistentes.
Revisar update_pgadmin.sh antes de executar.
Considerar adicionar healthcheck.

pgAdmin¶

Informações desta VPS¶

Estado¶

Ver o estado do serviço¶

Ver o container em execução¶

Ver o estado detalhado¶

Iniciar e parar¶

Iniciar o pgAdmin¶

Parar o pgAdmin¶

Reiniciar o pgAdmin¶

Recriar o container¶

Confirmar o estado¶

Acesso¶

Testar o domínio¶

Verificar o DNS¶

Ver detalhes da conexão¶

Logs¶

Ver os últimos 100 registros¶

Acompanhar os logs¶

Procurar erros¶

Procurar avisos¶

Versão¶

Ver a versão instalada¶

Ver a imagem configurada¶

Ver a imagem usada pelo container¶

Ver o identificador da imagem usada¶

Versão mais recente disponível¶

Verificar atualização disponível¶

Baixar a imagem mais recente¶

Ver o identificador da imagem baixada¶

Comparar com a imagem do container¶

Fixar uma versão¶

Backup¶

Criar diretório¶

Criar backup do Compose¶

Criar backup do .env¶

Ajustar permissões do backup do .env¶

Parar o pgAdmin¶

Criar backup do volume¶

Iniciar novamente¶

Listar backups¶

Atualização manual¶

Criar backup antes da atualização¶

Validar o Compose¶

Baixar a imagem¶

Recriar o serviço¶

Verificar o estado¶

Verificar os logs¶

Confirmar a versão¶

Testar o domínio¶

Atualização pelo script¶

Visualizar o conteúdo¶

Verificar permissões¶

Volume persistente¶

Ver as montagens¶

Inspecionar o volume¶

Ver espaço utilizado¶

Listar arquivos persistentes¶

Redes¶

Ver as redes do container¶

Verificar a rede proxy¶

Verificar a rede n8n¶

Conectar ao PostgreSQL do n8n¶

Porta interna¶

Confirmar as portas expostas¶

Confirmar a porta configurada no Traefik¶

Healthcheck¶

Verificar diretamente¶

Exemplo de healthcheck futuro¶

Traefik¶

Ver as labels¶

Ver logs do Traefik¶

Troubleshooting¶

pgAdmin não inicia¶

Erro de permissão no volume¶

Erro 404¶

Erro 502 ou Gateway Timeout¶

pgAdmin não conecta ao PostgreSQL¶

Login administrativo falha¶

Interface lenta¶

Criar backup do `.env`¶

Ajustar permissões do backup do `.env`¶