proxy-scraper/DEPLOY.md

Guia de Deploy - Proxy Scraping Service

Deploy Rápido (Quick Start)

Método 1: Script Automático (Recomendado)

./quick-start.sh

O script irá:

1. Verificar se Docker está rodando
2. Criar arquivo .env se não existir
3. Build das imagens Docker
4. Iniciar os serviços
5. Aguardar PostgreSQL estar pronto
6. Exibir status e instruções

Método 2: Manual com Makefile

# 1. Criar configuração
make setup

# 2. Editar .env (IMPORTANTE!)
nano .env
# Alterar pelo menos: POSTGRES_PASSWORD

# 3. Build e iniciar
make build
make up

# 4. Verificar logs
make logs

Método 3: Manual com Docker Compose

# 1. Criar .env
cp .env.example .env
nano .env  # Editar configurações

# 2. Build
docker-compose build

# 3. Iniciar
docker-compose up -d

# 4. Logs
docker-compose logs -f proxy-scraper

---

Configuração Inicial

1. Variáveis de Ambiente (.env)

Mínimo obrigatório:

POSTGRES_PASSWORD=sua_senha_segura_aqui

Configuração completa recomendada:

# PostgreSQL
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=proxies
POSTGRES_USER=postgres
POSTGRES_PASSWORD=SenhaForteAqui123!

# Proxy Validation
PROXY_TIMEOUT=10
VALIDATION_URL=http://httpbin.org/ip

# Scraping
SCRAPING_DELAY=2.0
MAX_RETRIES=3

# Schedule (UTC)
SCHEDULE_HOUR_START=2
SCHEDULE_HOUR_END=4

# Logging
LOG_LEVEL=INFO

# pgAdmin (opcional)
PGADMIN_EMAIL=admin@admin.com
PGADMIN_PASSWORD=AdminPass123!
PGADMIN_PORT=5050

2. Fontes de Proxy (proxies.txt)

Edite root/proxy/proxies.txt para adicionar ou remover fontes:

nano root/proxy/proxies.txt

Formato:

• Uma URL por linha
• Linhas com # são comentários
• URLs vazias são ignoradas

---

Verificação de Deploy

1. Verificar Status dos Containers

docker-compose ps

Deve mostrar:

• proxy-postgres - healthy
• proxy-scraper - running

2. Verificar Logs

# Logs do scraper
docker-compose logs -f proxy-scraper

# Logs do PostgreSQL
docker-compose logs postgres

# Todos os logs
docker-compose logs -f

3. Verificar Conectividade com Banco

# Testar conexão
docker-compose exec postgres psql -U postgres -d proxies -c "SELECT COUNT(*) FROM proxies;"

# Ver tabelas
docker-compose exec postgres psql -U postgres -d proxies -c "\dt"

# Ver índices
docker-compose exec postgres psql -U postgres -d proxies -c "\di"

4. Executar Scraping Teste

# Executar imediatamente (não aguardar agendamento)
docker-compose exec proxy-scraper python src/main.py --immediate

# Ou com make
make immediate

---

Deploy com pgAdmin (Interface Web)

1. Iniciar com pgAdmin

docker-compose --profile admin up -d

2. Acessar pgAdmin

1. Abra navegador: http://localhost:5050
2. Login:
   • Email: admin@admin.com (configurável em .env)
   • Senha: admin (configurável em .env)

3. Conectar ao PostgreSQL

1. Clique em "Add New Server"
2. General Tab:
   • Name: Proxy Database
3. Connection Tab:
   • Host: postgres
   • Port: 5432
   • Database: proxies
   • Username: postgres
   • Password: (sua senha do .env)
4. Clique "Save"

---

Monitoramento

Logs em Tempo Real

# Método 1: Docker Compose
docker-compose logs -f proxy-scraper

# Método 2: Makefile
make logs

# Método 3: Docker direto
docker logs -f proxy-scraper

Estatísticas do Banco

# Via Makefile
make stats

# Via Docker Compose
docker-compose exec postgres psql -U postgres -d proxies -c "
    SELECT
        COUNT(*) as total_proxies,
        COUNT(*) FILTER (WHERE is_active = TRUE) as active,
        COUNT(*) FILTER (WHERE is_anonymous = TRUE) as anonymous
    FROM proxies;"

Health Check

# Status geral
docker-compose ps

# Health do PostgreSQL
docker-compose exec postgres pg_isready -U postgres

# Health do scraper (via Python)
docker-compose exec proxy-scraper python -c "
import sys
sys.path.insert(0, '/app/src')
from database import DatabaseManager
db = DatabaseManager()
print('Database OK:', db.get_stats())
db.close()
"

---

Operações Comuns

Reiniciar Serviço

# Reiniciar tudo
docker-compose restart

# Reiniciar apenas scraper
docker-compose restart proxy-scraper

# Ou com Makefile
make restart

Parar Serviços

# Parar sem remover volumes (dados preservados)
docker-compose down

# Parar e remover volumes (LIMPA TUDO)
docker-compose down -v

Rebuild (Após Modificações no Código)

# Rebuild sem cache
docker-compose build --no-cache

# Restart após rebuild
docker-compose up -d

# Ou com Makefile
make build
make up

Ver Shell do Container

# Shell interativo
docker-compose exec proxy-scraper /bin/bash

# Executar comando único
docker-compose exec proxy-scraper ls -la /app

---

Troubleshooting Comum

Problema: Container não inicia

Diagnóstico:

docker-compose logs proxy-scraper
docker-compose ps

Soluções:

1. Verificar se .env existe e está correto
2. Verificar se proxies.txt existe
3. Rebuild: docker-compose build --no-cache
4. Verificar portas em uso: lsof -i :5432

Problema: PostgreSQL connection refused

Diagnóstico:

docker-compose logs postgres
docker-compose exec postgres pg_isready

Soluções:

1. Aguardar health check (30-60s após start)
2. Verificar credenciais no .env
3. Restart: docker-compose restart postgres
4. Verificar network: docker network ls

Problema: Nenhum proxy inserido

Diagnóstico:

# Ver logs detalhados
docker-compose exec proxy-scraper python src/main.py --immediate

# Com DEBUG
# Edite .env: LOG_LEVEL=DEBUG
docker-compose restart proxy-scraper
make logs

Causas comuns:

1. Proxies não são anônimos (validação falha)
2. Proxies já existem no banco
3. Fontes não estão respondendo
4. Timeout muito baixo

Soluções:

1. Verificar fontes em proxies.txt
2. Aumentar PROXY_TIMEOUT no .env
3. Testar manualmente as URLs
4. Ver estatísticas: make stats

Problema: Selenium/Chrome falha

Erro típico: "Chrome binary not found"

Soluções:

# Rebuild da imagem
docker-compose build --no-cache proxy-scraper
docker-compose up -d

# Verificar instalação do Chrome
docker-compose exec proxy-scraper google-chrome --version
docker-compose exec proxy-scraper chromedriver --version

Problema: Performance lenta

Otimizações:

1. Ajustar workers de validação:

   • Edite src/main.py
   • Linha com validate_proxies_bulk(proxies, max_workers=20)
   • Aumente para 30-50 (se CPU permitir)

2. Reduzir timeout:

   PROXY_TIMEOUT=5  # Reduzir de 10 para 5
   

3. Reduzir número de fontes:

   • Edite proxies.txt
   • Comente (#) fontes lentas

Problema: Disco cheio

Verificar uso:

# Tamanho dos volumes
docker system df -v

# Tamanho do banco
make stats

Limpeza:

# Limpar containers parados
docker container prune

# Limpar imagens antigas
docker image prune -a

# Limpar volumes não usados
docker volume prune

# CUIDADO: Remove TUDO (incluindo dados)
docker-compose down -v

---

Manutenção Periódica

Diária

• Verificar logs: make logs
• Ver estatísticas: make stats

Semanal

• Limpar proxies inativos antigos (via SQL - ver QUERIES.md)
• Verificar uso de disco
• Revisar fontes de proxy

Mensal

• Backup do banco de dados
• Atualizar dependências (requirements.txt)
• Rebuild das imagens: docker-compose build --no-cache

---

Backup e Restore

Backup do PostgreSQL

# Backup completo
docker-compose exec postgres pg_dump -U postgres proxies > backup_$(date +%Y%m%d).sql

# Backup comprimido
docker-compose exec postgres pg_dump -U postgres proxies | gzip > backup_$(date +%Y%m%d).sql.gz

# Apenas dados (sem schema)
docker-compose exec postgres pg_dump -U postgres --data-only proxies > backup_data.sql

Restore do PostgreSQL

# Restore completo
docker-compose exec -T postgres psql -U postgres proxies < backup_20251121.sql

# Restore de arquivo comprimido
gunzip -c backup_20251121.sql.gz | docker-compose exec -T postgres psql -U postgres proxies

# Restore apenas dados
docker-compose exec -T postgres psql -U postgres proxies < backup_data.sql

Backup Automatizado (Cron)

Adicione ao crontab:

# Editar crontab
crontab -e

# Adicionar linha (backup diário às 3 AM)
0 3 * * * cd /proxy && docker-compose exec postgres pg_dump -U postgres proxies | gzip > /path/to/backups/proxy_$(date +\%Y\%m\%d).sql.gz

---

Upgrade e Atualizações

Atualizar Código

# 1. Parar serviços
docker-compose down

# 2. Atualizar código (git pull ou manual)
# ... suas modificações ...

# 3. Rebuild
docker-compose build --no-cache

# 4. Iniciar
docker-compose up -d

# 5. Verificar
make logs

Atualizar Dependências Python

# 1. Editar requirements.txt
nano requirements.txt

# 2. Rebuild
docker-compose build --no-cache proxy-scraper

# 3. Restart
docker-compose up -d proxy-scraper

Migrar para Novo Servidor

# No servidor antigo:
# 1. Backup
docker-compose exec postgres pg_dump -U postgres proxies | gzip > proxy_migration.sql.gz

# 2. Copiar arquivos do projeto
tar -czf proxy_project.tar.gz /proxy

# No servidor novo:
# 1. Extrair projeto
tar -xzf proxy_project.tar.gz

# 2. Deploy
cd proxy
./quick-start.sh

# 3. Aguardar inicialização
sleep 30

# 4. Restore backup
gunzip -c proxy_migration.sql.gz | docker-compose exec -T postgres psql -U postgres proxies

# 5. Verificar
make stats

---

Segurança em Produção

Checklist de Segurança

• Alterar senha do PostgreSQL
• Alterar senha do pgAdmin
• Não expor porta 5432 externamente
• Usar firewall (UFW, iptables)
• Configurar SSL/TLS para pgAdmin
• Logs em volume separado
• Backup automático configurado
• Monitoring configurado
• Rate limiting nas fontes
• Atualizar dependências regularmente

Configuração de Firewall (UFW)

# Permitir apenas localhost no PostgreSQL
sudo ufw deny 5432/tcp
sudo ufw allow from 127.0.0.1 to any port 5432

# Se usar pgAdmin remotamente (CUIDADO!)
sudo ufw allow 5050/tcp
# Recomendado: usar VPN ou SSH tunnel

Remover Porta do PostgreSQL (Produção)

Edite docker-compose.yml:

postgres:
  # Remover/comentar esta seção:
  # ports:
  #   - "5432:5432"

Restart:

docker-compose up -d

---

Métricas e Observabilidade

Prometheus + Grafana (Futuro)

Adicionar ao docker-compose.yml:

prometheus:
  image: prom/prometheus
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
  ports:
    - "9090:9090"

grafana:
  image: grafana/grafana
  ports:
    - "3000:3000"

Logs Centralizados (ELK Stack)

Para ambientes maiores, considere:

• Elasticsearch
• Logstash
• Kibana

---

Conclusão

Este guia cobre os cenários mais comuns de deploy e operação. Para detalhes técnicos, consulte:

• README.md - Documentação geral
• ARCHITECTURE.md - Arquitetura técnica
• QUERIES.md - SQL queries úteis
• PROJECT_SUMMARY.txt - Resumo executivo

Para suporte adicional, consulte os logs e documentação do Docker/PostgreSQL.

Projeto pronto para produção!