# Guia para Instalação com Docker

### 📋 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

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

```bash
cd zpro.io
```

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

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

3. **Construa as imagens e inicie os serviços**:

```bash
# 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.

4. **Verifique os logs**:

```bash
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:**

```12:20: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:**

```42:43: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:**

```66:66:docker-compose.yml
      PORT: ${PORT:-7563}
```

```121:122:docker-compose.yml
    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:**

```172:173: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:**

```70:70:docker-compose.yml
      BACKEND_URL: ${BACKEND_URL:-https://dockerapi.comunidadezdg.com.br}
```

```138:143:docker-compose.yml
      - "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`:

  ```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:**

```71:71:docker-compose.yml
      FRONTEND_URL: ${FRONTEND_URL:-https://dockerapp.comunidadezdg.com.br}
```

```182:187:docker-compose.yml
      - "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`:

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

**3. Dashboard do Traefik**

**Localização no docker-compose.yml:**

```29:29: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`:

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

```env
# 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
ACME_EMAIL=seu-email@exemplo.com

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

1. **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)
2. **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:**

```14:16:docker-compose.yml
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL:-comunidadezdg@gmail.com}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
```

**Para alterar o email:**

* Defina `ACME_EMAIL=seu-email@exemplo.com` no arquivo `.env`

### 🎯 Comandos Úteis

#### Construir as imagens

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
docker-compose restart backend
docker-compose restart frontend

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

#### Reconstruir as imagens

```bash
# 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

```bash
docker-compose ps
```

#### Acessar o shell de um container

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

### 🔍 Verificação da Instalação

Após iniciar os serviços, verifique:

1. **Backend**: Acesse `https://SEU_BACKEND_DOMAIN:8443` ou `http://SEU_BACKEND_DOMAIN:81`
2. **Frontend**: Acesse `https://SEU_FRONTEND_DOMAIN:8443` ou `http://SEU_FRONTEND_DOMAIN:81`
3. **Dashboard Traefik**: Acesse `http://SEU_TRAEFIK_DOMAIN:8080` ou `http://SEU_TRAEFIK_DOMAIN:81`
4. **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/>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ajuda.zdg.com.br/avancado-recursos-tecnicos/boas-praticas-de-infraestrutura/guia-para-instalacao-com-docker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.