todolist-fullstack/DOCKER_SETUP_GUIDE.md

🐳 Docker Setup Guide - Task Manager Backend

📋 Pré-requisitos

Você precisa ter instalado:

• ✅ Docker Desktop
• ✅ Docker Compose (vem com Docker Desktop)

Verificar instalação:

docker --version
docker-compose --version

---

🚀 Quick Start

1. Build da Imagem Docker

# Navegar para o diretório do projeto
cd c:\Users\Erik Silva\Documents\projetos\to-do-list

# Fazer build da imagem (primeira vez)
docker build -t todolist-backend:latest ./backend-api

Esperado:

[+] Building 45.3s (15/15) FINISHED
 => => naming to docker.io/library/todolist-backend:latest

2. Rodar o Container

Opção A: Com Docker Compose (RECOMENDADO)

# Iniciar todos os serviços
docker-compose up -d

# Ver logs
docker-compose logs -f backend

# Parar serviços
docker-compose down

Opção B: Direto com Docker

# Rodar container
docker run -d \
  --name todolist-backend \
  -p 3000:3000 \
  -e SUPABASE_URL=https://seu-projeto.supabase.co \
  -e SUPABASE_ANON_KEY=sua-anon-key \
  -e SUPABASE_SERVICE_KEY=sua-service-key \
  -e JWT_SECRET=sua-chave-secreta-32-chars \
  todolist-backend:latest

# Ver logs
docker logs -f todolist-backend

# Parar container
docker stop todolist-backend
docker rm todolist-backend

3. Testar a API

# Health check
curl http://localhost:3000/api

# Criar usuário
curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"Test123456"}'

---

📦 Estrutura do Dockerfile

STAGE 1: BUILDER (Multi-stage)
├── Node 20 Alpine
├── npm ci (instalar dependências)
├── npm run build (compilar TypeScript)

STAGE 2: RUNNER (Otimizado para produção)
├── Node 20 Alpine (imagem limpa)
├── npm ci --only=production (sem devDependencies)
├── Usuário não-root (nodejs)
├── Health check configurado
└── 150-200 MB de tamanho final

---

🔧 Configuração com Variáveis de Ambiente

Arquivo .env (LOCAL)

# Copiar template
cp backend-api/.env.example backend-api/.env

# Editar com seus valores
nano backend-api/.env

Conteúdo de exemplo:

NODE_ENV=development
PORT=3000
API_PREFIX=/api

# Supabase
SUPABASE_URL=https://abcdefghijk.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# JWT
JWT_SECRET=sua-chave-secreta-com-minimo-32-caracteres
JWT_EXPIRATION=7d

Variáveis em docker-compose.yml

environment:
  NODE_ENV: development
  SUPABASE_URL: ${SUPABASE_URL:-default-value}
  # ... outras variáveis

Usar arquivo .env (NÃO recomendado para produção):

docker-compose --env-file backend-api/.env up

---

📊 Comandos Úteis

Build e Imagens

# Fazer build
docker build -t todolist-backend:latest ./backend-api

# Listar imagens
docker images | grep todolist

# Inspecionar imagem
docker inspect todolist-backend:latest

# Remover imagem
docker rmi todolist-backend:latest

Containers

# Listar containers
docker ps -a

# Ver logs
docker logs todolist-backend
docker logs -f todolist-backend        # Follow (tempo real)
docker logs --tail 50 todolist-backend # Últimas 50 linhas

# Executar comando no container
docker exec -it todolist-backend sh

# Ver recursos utilizados
docker stats todolist-backend

# Remover container
docker rm todolist-backend

Docker Compose

# Iniciar
docker-compose up              # foreground
docker-compose up -d           # background

# Ver status
docker-compose ps

# Ver logs
docker-compose logs -f backend
docker-compose logs backend --tail 50

# Recriar containers
docker-compose restart

# Remover tudo
docker-compose down            # para containers
docker-compose down -v         # remove também volumes

---

🔍 Health Check

O Dockerfile inclui um health check automático:

# Ver status
docker inspect --format='{{json .State.Health}}' todolist-backend

# Esperado:
# {"Status":"healthy","FailingStreak":0,"Passes":1,"Fails":0}

---

🚀 Otimizações

Tamanho da Imagem

# Verificar tamanho
docker images todolist-backend

# REPOSITORY              TAG       SIZE
# todolist-backend        latest    180MB

# Reduzir size:
# - Alpine Linux: 180MB (atual) vs 900MB (sem alpine)
# - Multi-stage build: elimina dependências de build

Performance

# npm ci vs npm install
# - npm ci: mais rápido, dependências exatas
# - Ideal para CI/CD e Docker

# .dockerignore
# - Reduz contexto de build
# - Evita copiar arquivos desnecessários

---

⚠️ Troubleshooting

Erro: "Cannot find module"

# Problema: node_modules não instalado no container
# Solução:
docker-compose down
docker-compose build --no-cache
docker-compose up

Erro: "EADDRINUSE: address already in use :::3000"

# Problema: Porta 3000 já está em uso
# Solução 1: Usar porta diferente
docker run -p 3001:3000 todolist-backend:latest

# Solução 2: Matar processo que está usando porta 3000
lsof -i :3000
kill -9 <PID>

Erro: Variáveis de ambiente não funcionam

# Problema: .env não está sendo lido
# Solução: Usar docker-compose ou passar com -e

# ❌ Não funciona:
docker run todolist-backend:latest

# ✅ Funciona:
docker run -e SUPABASE_URL=... todolist-backend:latest
docker-compose up # lê .env automaticamente

Health check falhando

# Verificar logs
docker logs todolist-backend

# Testar manualmente
docker exec todolist-backend curl http://localhost:3000/api

# Se falhar, a API não está respondendo
# Verificar: .env, credenciais Supabase, conexão de rede

---

📚 Referências

• 📖 Docker Docs
• 📖 Docker Compose Guide
• 📖 Best Practices
• 🐳 Alpine Linux - Imagem base

---

✅ Próximos Passos

1. ✅ Dockerfile criado e testado
2. ➡️ Fazer commit (feat(docker): Add Dockerfile and docker-compose)
3. ➡️ Frontend Next.js (Fase 2) - Próximo grande passo

---

Status: 🐳 Docker ready for local development e produção!