Hugging Face's logo

Spaces:
neural-thinker
/
cidadao.ai-backend
Paused

App Files Community
cidadao.ai-backend / docs /deployment /README.md
anderson-ufrj
refactor: complete repository reorganization and documentation update
92d464e
preview code
|
raw
history blame contribute delete
9.01 kB

🚀 Guia de Deployment - Cidadão.AI Backend

Autor: Anderson Henrique da Silva
Última Atualização: 2025-09-25 18:30:00 -03:00 (São Paulo, Brasil)

English version below

📊 Estado Atual

O sistema está atualmente em produção no HuggingFace Spaces com configuração simplificada (sem PostgreSQL/Redis).

🎯 Opções de Deploy

1. HuggingFace Spaces (Atual) ✅

Prós: Gratuito, fácil, CI/CD automático
Contras: Sem banco de dados persistente, recursos limitados

# Deploy automático via push
git remote add hf https://huggingface.co/spaces/SEU_USUARIO/cidadao-ai
git push hf main

Configuração no HuggingFace:

  1. Crie um Space com SDK Docker
  2. Configure as secrets:
    • GROQ_API_KEY
    • JWT_SECRET_KEY
    • TRANSPARENCY_API_KEY (opcional)

2. Docker Local 🐳

Para desenvolvimento e testes:

# Build e execução básica
docker build -t cidadao-ai .
docker run -p 8000:8000 --env-file .env cidadao-ai

# Com docker-compose (inclui Redis)
docker-compose up -d

# Com monitoramento completo
docker-compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

3. VPS com Docker 🖥️

Para produção completa com banco de dados:

# 1. Configure o servidor (Ubuntu 22.04)
ssh usuario@seu-servidor
sudo apt update && sudo apt install docker.io docker-compose

# 2. Clone o projeto
git clone https://github.com/seu-usuario/cidadao.ai-backend
cd cidadao.ai-backend

# 3. Configure variáveis
cp .env.example .env
nano .env  # Configure todas as variáveis

# 4. Execute
docker-compose -f docker-compose.production.yml up -d

4. Kubernetes ☸️

Para alta disponibilidade:

# Apply configurações
kubectl apply -f k8s/

# Verificar pods
kubectl get pods -n cidadao-ai

# Expor serviço
kubectl expose deployment cidadao-api --type=LoadBalancer --port=80

🔑 Variáveis de Ambiente

Essenciais (Obrigatórias) 

# Autenticação
JWT_SECRET_KEY=gere-com-openssl-rand-hex-32
SECRET_KEY=outra-chave-aleatoria

# LLM Provider
GROQ_API_KEY=sua-chave-groq

Opcionais (Recursos Extras) 

# Portal da Transparência (sem isso usa dados demo)
TRANSPARENCY_API_KEY=sua-chave-api

# Banco de Dados (sem isso usa memória)
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/cidadao

# Cache Redis (sem isso usa memória)
REDIS_URL=redis://localhost:6379

# Configurações de Performance
WORKERS=4
MAX_AGENTS=10
CACHE_TTL=3600

📋 Checklist de Deploy

Produção Mínima (HuggingFace)

  • Configurar secrets no HF Spaces
  • Verificar app.py está usando configuração minimal
  • Push para branch hf-fastapi
  • Testar endpoints básicos

Produção Completa (VPS/Cloud)

  • Servidor com mínimo 2GB RAM
  • Docker e docker-compose instalados
  • PostgreSQL configurado
  • Redis configurado (opcional)
  • SSL/TLS configurado (Nginx + Certbot)
  • Backup configurado
  • Monitoramento ativo

📊 Monitoramento

Endpoints de Health Check 

# Básico
curl https://seu-dominio/health

# Detalhado (requer auth)
curl -H "Authorization: Bearer $TOKEN" https://seu-dominio/health/detailed

# Métricas Prometheus
curl https://seu-dominio/metrics

Grafana Dashboards

Se usando docker-compose com monitoramento:

Dashboards disponíveis:

  • System Overview
  • Agent Performance
  • API Metrics
  • Cache Analytics

🚨 Troubleshooting

Erro: "No module named 'src'" 

# Adicione ao Dockerfile ou startup
export PYTHONPATH=/app:$PYTHONPATH

Erro: Redis connection failed

O sistema funciona sem Redis, mas se quiser ativar:

docker run -d --name redis -p 6379:6379 redis:alpine

Erro: Database connection failed

O sistema usa memória se não encontrar PostgreSQL. Para ativar:

docker run -d --name postgres \
  -e POSTGRES_DB=cidadao \
  -e POSTGRES_USER=cidadao \
  -e POSTGRES_PASSWORD=senha \
  -p 5432:5432 \
  postgres:15-alpine

Performance Lenta

  1. Verifique CPU/RAM: docker stats
  2. Aumente workers: WORKERS=8
  3. Ative cache Redis
  4. Use agent pooling

🔒 Segurança

Configurações Essenciais

  1. Sempre gere novas chaves secretas
  2. Nunca commite .env no git
  3. Use HTTPS em produção
  4. Configure rate limiting
  5. Mantenha dependências atualizadas

Gerar Chaves Seguras 

# JWT Secret
openssl rand -hex 32

# Secret Key
python -c "import secrets; print(secrets.token_urlsafe(32))"

🚀 Deployment Guide - Cidadão.AI Backend (English)

Author: Anderson Henrique da Silva
Last Updated: 2025-09-25 18:30:00 -03:00 (São Paulo, Brazil)

📊 Current Status

The system is currently in production on HuggingFace Spaces with simplified configuration (no PostgreSQL/Redis).

🎯 Deployment Options

1. HuggingFace Spaces (Current) ✅

Pros: Free, easy, automatic CI/CD
Cons: No persistent database, limited resources

# Automatic deployment via push
git remote add hf https://huggingface.co/spaces/YOUR_USER/cidadao-ai
git push hf main

HuggingFace Configuration:

  1. Create a Space with Docker SDK
  2. Configure secrets:
    • GROQ_API_KEY
    • JWT_SECRET_KEY
    • TRANSPARENCY_API_KEY (optional)

2. Local Docker 🐳

For development and testing:

# Basic build and run
docker build -t cidadao-ai .
docker run -p 8000:8000 --env-file .env cidadao-ai

# With docker-compose (includes Redis)
docker-compose up -d

# With complete monitoring
docker-compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

3. VPS with Docker 🖥️

For complete production with database:

# 1. Configure server (Ubuntu 22.04)
ssh user@your-server
sudo apt update && sudo apt install docker.io docker-compose

# 2. Clone project
git clone https://github.com/your-user/cidadao.ai-backend
cd cidadao.ai-backend

# 3. Configure variables
cp .env.example .env
nano .env  # Configure all variables

# 4. Run
docker-compose -f docker-compose.production.yml up -d

4. Kubernetes ☸️

For high availability:

# Apply configurations
kubectl apply -f k8s/

# Check pods
kubectl get pods -n cidadao-ai

# Expose service
kubectl expose deployment cidadao-api --type=LoadBalancer --port=80

🔑 Environment Variables

Essential (Required) 

# Authentication
JWT_SECRET_KEY=generate-with-openssl-rand-hex-32
SECRET_KEY=another-random-key

# LLM Provider
GROQ_API_KEY=your-groq-key

Optional (Extra Features) 

# Portal da Transparência (without this uses demo data)
TRANSPARENCY_API_KEY=your-api-key

# Database (without this uses memory)
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/cidadao

# Redis Cache (without this uses memory)
REDIS_URL=redis://localhost:6379

# Performance Settings
WORKERS=4
MAX_AGENTS=10
CACHE_TTL=3600

📋 Deployment Checklist

Minimum Production (HuggingFace)

  • Configure secrets in HF Spaces
  • Verify app.py is using minimal configuration
  • Push to hf-fastapi branch
  • Test basic endpoints

Complete Production (VPS/Cloud)

  • Server with minimum 2GB RAM
  • Docker and docker-compose installed
  • PostgreSQL configured
  • Redis configured (optional)
  • SSL/TLS configured (Nginx + Certbot)
  • Backup configured
  • Active monitoring

📊 Monitoring

Health Check Endpoints 

# Basic
curl https://your-domain/health

# Detailed (requires auth)
curl -H "Authorization: Bearer $TOKEN" https://your-domain/health/detailed

# Prometheus metrics
curl https://your-domain/metrics

Grafana Dashboards

If using docker-compose with monitoring:

Available dashboards:

  • System Overview
  • Agent Performance
  • API Metrics
  • Cache Analytics

🚨 Troubleshooting

Error: "No module named 'src'" 

# Add to Dockerfile or startup
export PYTHONPATH=/app:$PYTHONPATH

Error: Redis connection failed

System works without Redis, but to enable:

docker run -d --name redis -p 6379:6379 redis:alpine

Error: Database connection failed

System uses memory if PostgreSQL not found. To enable:

docker run -d --name postgres \
  -e POSTGRES_DB=cidadao \
  -e POSTGRES_USER=cidadao \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  postgres:15-alpine

Slow Performance

  1. Check CPU/RAM: docker stats
  2. Increase workers: WORKERS=8
  3. Enable Redis cache
  4. Use agent pooling

🔒 Security

Essential Settings

  1. Always generate new secret keys
  2. Never commit .env to git
  3. Use HTTPS in production
  4. Configure rate limiting
  5. Keep dependencies updated

Generate Secure Keys 

# JWT Secret
openssl rand -hex 32

# Secret Key
python -c "import secrets; print(secrets.token_urlsafe(32))"