Guia para Instalação com Docker

Este guia explica como instalar e configurar o ZPRO Passaporte usando Docker Compose

📋 Pré-requisitos

Docker instalado (versão 20.10 ou superior)
Docker Compose instalado (versão 2.0 ou superior)
Acesso root/sudo (para Linux) ou permissões de administrador (para Windows)
Domínio configurado com DNS apontando para o servidor (para produção com SSL)

🚀 Instalação Rápida

Clone o repositório (se ainda não tiver):

cd zpro.io

Configure as variáveis de ambiente (opcional, pode definir no docker-compose.yml):

cp .env.example .env  # Se existir um arquivo .env.example
# Edite o arquivo .env com suas configurações

Construa as imagens e inicie os serviços:

# Opção 1: Build e start em um único comando (recomendado)
docker-compose up -d --build

# Opção 2: Build primeiro, depois start
docker-compose build
docker-compose up -d

⚠️ Importante: Como os serviços backend e frontend precisam ser construídos a partir dos Dockerfiles, é necessário fazer o build das imagens antes de iniciar. Use --build no comando up ou execute build separadamente.

Verifique os logs:

docker-compose logs -f

⚙️ Configuração de Portas e Subdomínios

📍 Onde Configurar Portas

As portas são configuradas diretamente no arquivo docker-compose.yml ou através de variáveis de ambiente no arquivo .env.

1. Traefik (Reverse Proxy)

Localização no docker-compose.yml:

      - "--entrypoints.web.address=:81"
      - "--entrypoints.websecure.address=:8443"
    ports:
      - "81:81"      # HTTP
      - "8443:8443"  # HTTPS (porta alternativa para não conflitar com nginx na 443)
      - "8080:8080"  # Dashboard do Traefik

Configuração:

Porta HTTP: 81 (linha 12 e 18) - Para alterar, modifique ambas as linhas
Porta HTTPS: 8443 (linha 13 e 19) - Para alterar, modifique ambas as linhas
Dashboard Traefik: 8080 (linha 20) - Interface de gerenciamento do Traefik

2. PostgreSQL (Banco de Dados)

Localização no docker-compose.yml:

    ports:
      - "${DB_PORT:-7544}:5432"

Configuração:

Porta Externa: Configurada via variável DB_PORT (padrão: 7544)
Porta Interna: 5432 (porta padrão do PostgreSQL, não alterar)
Para alterar, defina DB_PORT=PORTA_DESEJADA no arquivo .env

3. Backend

Localização no docker-compose.yml:

      PORT: ${PORT:-7563}

    ports:
      - "${PORT:-7563}:7563"

Configuração:

Porta Externa: Configurada via variável PORT (padrão: 7563)
Porta Interna: 7563 (porta interna do container, não alterar)
Para alterar, defina PORT=PORTA_DESEJADA no arquivo .env

4. Frontend

Localização no docker-compose.yml:

    ports:
      - "7564:4444"

Configuração:

Porta Externa: 7564 (porta do host)
Porta Interna: 4444 (porta interna do container)
Para alterar a porta externa, modifique 7564 na linha 173

🌐 Onde Configurar Subdomínios

Os subdomínios são configurados através de variáveis de ambiente e labels do Traefik no docker-compose.yml.

1. Backend (API)

Localização no docker-compose.yml:

      BACKEND_URL: ${BACKEND_URL:-https://dockerapi.comunidadezdg.com.br}

      - "traefik.http.routers.backend.rule=Host(`${BACKEND_DOMAIN:-api.localhost}`)"
      - "traefik.http.routers.backend.entrypoints=web"
      - "traefik.http.routers.backend.service=backend"
      - "traefik.http.services.backend.loadbalancer.server.port=7563"
      # HTTPS ativo na porta 8443 (para não conflitar com nginx na 443)
      - "traefik.http.routers.backend-secure.rule=Host(`${BACKEND_DOMAIN:-dockerapi.comunidadezdg.com.br}`)"

Configuração:

Variável: BACKEND_DOMAIN (padrão: dockerapi.comunidadezdg.com.br para HTTPS, api.localhost para HTTP)
URL Completa: BACKEND_URL (deve incluir o protocolo https://)

Para alterar, defina no arquivo .env:

BACKEND_DOMAIN=api.seudominio.com.br
BACKEND_URL=https://api.seudominio.com.br

2. Frontend (Aplicação Web)

Localização no docker-compose.yml:

      FRONTEND_URL: ${FRONTEND_URL:-https://dockerapp.comunidadezdg.com.br}

      - "traefik.http.routers.frontend.rule=Host(`${FRONTEND_DOMAIN:-localhost}`)"
      - "traefik.http.routers.frontend.entrypoints=web"
      - "traefik.http.routers.frontend.service=frontend"
      - "traefik.http.services.frontend.loadbalancer.server.port=4444"
      # HTTPS ativo na porta 8443 (para não conflitar com nginx na 443)
      - "traefik.http.routers.frontend-secure.rule=Host(`${FRONTEND_DOMAIN:-dockerapp.comunidadezdg.com.br}`)"

Configuração:

Variável: FRONTEND_DOMAIN (padrão: dockerapp.comunidadezdg.com.br para HTTPS, localhost para HTTP)
URL Completa: FRONTEND_URL (deve incluir o protocolo https://)

Para alterar, defina no arquivo .env:

FRONTEND_DOMAIN=app.seudominio.com.br
FRONTEND_URL=https://app.seudominio.com.br

3. Dashboard do Traefik

Localização no docker-compose.yml:

      - "traefik.http.routers.traefik.rule=Host(`${TRAEFIK_DASHBOARD_DOMAIN:-traefik.localhost}`)"

Configuração:

Variável: TRAEFIK_DASHBOARD_DOMAIN (padrão: traefik.localhost)

Para alterar, defina no arquivo .env:

TRAEFIK_DASHBOARD_DOMAIN=dashboard.seudominio.com.br

📝 Arquivo .env de Exemplo

Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

# Ambiente
NODE_ENV=production

# Portas
PORT=7563
DB_PORT=7544
PROXY_PORT=8443

# Domínios e URLs
BACKEND_DOMAIN=api.seudominio.com.br
BACKEND_URL=https://api.seudominio.com.br
FRONTEND_DOMAIN=app.seudominio.com.br
FRONTEND_URL=https://app.seudominio.com.br
TRAEFIK_DASHBOARD_DOMAIN=dashboard.seudominio.com.br
ADMIN_DOMAIN=zpro.io

# Banco de Dados
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sua_senha_segura_aqui
POSTGRES_DB=postgres
DB_DIALECT=postgres
DB_PORT=5432
POSTGRES_HOST=postgres

# JWT Secrets (gere novos secrets para produção)
JWT_SECRET=seu_jwt_secret_aqui
JWT_REFRESH_SECRET=seu_jwt_refresh_secret_aqui

# Let's Encrypt
[email protected]

# Outras configurações
IMAGE_SOURCE=https://zdg.dev.br/

🔧 Configuração de DNS

Para que os certificados SSL funcionem corretamente, você precisa configurar os registros DNS:

Registro A ou CNAME apontando para o IP do servidor:
- api.seudominio.com.br → IP do servidor
- app.seudominio.com.br → IP do servidor
- dashboard.seudominio.com.br → IP do servidor (opcional)
Portas abertas no firewall:
- 81 (HTTP)
- 8443 (HTTPS)
- 8080 (Dashboard Traefik - opcional, apenas para acesso interno)

🔐 Certificados SSL

O Traefik está configurado para obter certificados SSL automaticamente via Let's Encrypt usando o desafio TLS.

Configuração no docker-compose.yml:

      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL:[email protected]}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"

Para alterar o email:

Defina [email protected] no arquivo .env

🎯 Comandos Úteis

Construir as imagens

# Build de todas as imagens
docker-compose build

# Build forçando reconstrução completa (sem cache)
docker-compose build --no-cache

# Build de um serviço específico
docker-compose build backend
docker-compose build frontend

Iniciar os serviços

# Iniciar sem build (usa imagens já construídas)
docker-compose up -d

# Iniciar com build automático (recomendado na primeira vez)
docker-compose up -d --build

# Iniciar e ver logs em tempo real
docker-compose up

Parar os serviços

# Parar os serviços (mantém containers e volumes)
docker-compose stop

# Parar e remover containers (mantém volumes)
docker-compose down

# Parar, remover containers e volumes (⚠️ apaga dados)
docker-compose down -v

Ver logs

# Todos os serviços
docker-compose logs -f

# Serviço específico
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres
docker-compose logs -f traefik

# Últimas 100 linhas de um serviço
docker-compose logs --tail=100 backend

Reiniciar um serviço específico

docker-compose restart backend
docker-compose restart frontend

# Reiniciar com rebuild
docker-compose up -d --build backend

Reconstruir as imagens

# Reconstruir tudo do zero (sem cache)
docker-compose build --no-cache
docker-compose up -d

# Reconstruir um serviço específico
docker-compose build --no-cache backend
docker-compose up -d backend

Verificar status dos containers

docker-compose ps

Acessar o shell de um container

docker-compose exec backend sh
docker-compose exec postgres psql -U postgres

🔍 Verificação da Instalação

Após iniciar os serviços, verifique:

Backend: Acesse https://SEU_BACKEND_DOMAIN:8443 ou http://SEU_BACKEND_DOMAIN:81
Frontend: Acesse https://SEU_FRONTEND_DOMAIN:8443 ou http://SEU_FRONTEND_DOMAIN:81
Dashboard Traefik: Acesse http://SEU_TRAEFIK_DOMAIN:8080 ou http://SEU_TRAEFIK_DOMAIN:81
PostgreSQL: Conecte-se em localhost:PORTA_DB (padrão: 7544)

⚠️ Troubleshooting

Porta já em uso

Se uma porta estiver em uso, altere a configuração no docker-compose.yml ou no arquivo .env.

Certificado SSL não funciona

Verifique se os DNS estão apontando corretamente
Certifique-se de que as portas 81 e 8443 estão abertas no firewall
Verifique os logs do Traefik: docker-compose logs traefik

Container não inicia

Verifique os logs: docker-compose logs [nome-do-servico]
Verifique se todas as variáveis de ambiente estão configuradas
Certifique-se de que o Docker tem permissões suficientes

Erro de conexão com banco de dados

Verifique se o PostgreSQL está rodando: docker-compose ps postgres
Verifique as credenciais no arquivo .env
Verifique se a porta do banco está acessível

📚 Estrutura do Projeto

zpro-passaporte/
├── docker-compose.yml    # Configuração dos serviços
├── .env                  # Variáveis de ambiente (criar)
├── backend/              # Código do backend
├── frontend/             # Código do frontend
└── README.md             # Este arquivo

🆘 Suporte

Para mais informações ou problemas, consulte a documentação do projeto ou entre em contato com a equipe de suporte. https://suporte.zdg.com.br/

AnteriorBoas práticas de Infraestrutura PróximoConfiguração do Traefik com Nginx

Atualizado há 1 mês

hashtag📋 Pré-requisitos

hashtag🚀 Instalação Rápida

hashtag⚙️ Configuração de Portas e Subdomínios

hashtag📍 Onde Configurar Portas

hashtag🌐 Onde Configurar Subdomínios

hashtag📝 Arquivo .env de Exemplo

hashtag🔧 Configuração de DNS

hashtag🔐 Certificados SSL

hashtag🎯 Comandos Úteis

hashtagConstruir as imagens

hashtagIniciar os serviços

hashtagParar os serviços

hashtagVer logs

hashtagReiniciar um serviço específico

hashtagReconstruir as imagens

hashtagVerificar status dos containers

hashtagAcessar o shell de um container

hashtag🔍 Verificação da Instalação

hashtag⚠️ Troubleshooting

hashtagPorta já em uso

hashtagCertificado SSL não funciona

hashtagContainer não inicia

hashtagErro de conexão com banco de dados

hashtag📚 Estrutura do Projeto

hashtag🆘 Suporte

📋 Pré-requisitos

🚀 Instalação Rápida

⚙️ Configuração de Portas e Subdomínios

📍 Onde Configurar Portas

🌐 Onde Configurar Subdomínios

📝 Arquivo .env de Exemplo

🔧 Configuração de DNS

🔐 Certificados SSL

🎯 Comandos Úteis

Construir as imagens

Iniciar os serviços

Parar os serviços

Ver logs

Reiniciar um serviço específico

Reconstruir as imagens

Verificar status dos containers

Acessar o shell de um container

🔍 Verificação da Instalação

⚠️ Troubleshooting

Porta já em uso

Certificado SSL não funciona

Container não inicia

Erro de conexão com banco de dados

📚 Estrutura do Projeto

🆘 Suporte