DEPLOY.md

# Guia de Deploy - RAG Template

Guia completo para fazer deploy do RAG Template em multiplas plataformas.

---

## Visao Geral

Este guia cobre deploy em:
1. **Hugging Face Spaces** - Deploy facil e gratuito
2. **Railway** - Full-stack deployment
3. **Docker Local** - Para producao local
4. **VPS/Cloud** - Deploy customizado

---

## 1. Hugging Face Spaces (Recomendado para Demo)

### Pre-requisitos
- Conta no [Hugging Face](https://huggingface.co)
- Database externo configurado (Supabase/Neon)

### Passo a Passo

#### 1.1. Criar Space

## Pré-requisitos

- Git instalado
- Conta no GitHub: https://github.com/guifav
- Conta no Hugging Face: https://huggingface.co/guifav
- Repositório criado: https://github.com/guifav/rag_template
- Space criado: https://huggingface.co/spaces/guifav/rag_template

1. Va para [huggingface.co/spaces](https://huggingface.co/spaces)
2. Clique em "Create new Space"
3. Configure:
   - Name: `rag-template`
   - License: MIT
   - SDK: Gradio
   - Hardware: CPU basic (free)

#### 1.2. Clonar e Push

```bash
# Clone seu Space
git clone https://huggingface.co/spaces/SEU_USERNAME/rag-template
cd rag-template

# Copie arquivos do projeto
cp -r ../rag_template/* .

# Use README_SPACES.md como README.md
cp README_SPACES.md README.md

# Commit e push
git add .
git commit -m "Initial deploy"
git push
```

#### 1.3. Configurar Secrets

1. Va para Settings do Space
2. Adicione em "Repository secrets":

```env
DATABASE_URL=postgresql://user:pass@host:port/db
HF_TOKEN=seu_token_aqui
```

**Opcional**:
```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

Veja guia completo: [docs/SPACES_SECRETS.md](docs/SPACES_SECRETS.md)

#### 1.4. Verificar Deploy

Aguarde 2-3 minutos para build. Acesse seu Space:
```
https://huggingface.co/spaces/SEU_USERNAME/rag-template
```

### Limitacoes

- Cold start: 30-60s
- CPU only (sem GPU)
- 16GB RAM
- Timeout: 60s

Veja: [docs/SPACES_LIMITATIONS.md](docs/SPACES_LIMITATIONS.md)

---

## 2. Railway

### Pre-requisitos
- Conta no [Railway](https://railway.app)
- GitHub account

### Passo a Passo

#### 2.1. Criar Projeto

1. Acesse [railway.app](https://railway.app)
2. "New Project" → "Deploy from GitHub repo"
3. Selecione repositorio `rag_template`

#### 2.2. Adicionar PostgreSQL

1. No projeto, clique "+ New"
2. "Database" → "Add PostgreSQL"
3. Railway cria banco automaticamente

#### 2.3. Habilitar pgvector

```bash
# Instale Railway CLI
npm i -g @railway/cli

# Login e link
railway login
railway link

# Conecte ao PostgreSQL
railway run psql $DATABASE_URL

# Execute:
CREATE EXTENSION vector;
\q
```

#### 2.4. Configurar Variaveis

No servico app, adicione:

```env
DATABASE_URL=${{Postgres.DATABASE_URL}}
HF_TOKEN=seu_token
PORT=7860
```

#### 2.5. Deploy

Railway faz deploy automatico a cada push no GitHub!

Veja guia completo: [docs/RAILWAY_SETUP.md](docs/RAILWAY_SETUP.md)

---

## 3. Docker Local/Producao

### Pre-requisitos
- Docker e Docker Compose instalados
- Database externo OU use o PostgreSQL no compose

### Opcao A: Com Database Externo

```bash
# Configure .env
cp .env.example .env
# Edite .env com DATABASE_URL do Supabase/Neon

# Build e run apenas o app
docker build -f docker/Dockerfile.prod -t rag-template .
docker run -p 7860:7860 --env-file .env rag-template
```

### Opcao B: Stack Completa (App + PostgreSQL)

```bash
# Configure .env
cp .env.example .env
# Configure POSTGRES_PASSWORD e outras vars

# Suba stack completa
docker-compose -f docker/docker-compose.prod.yml up -d

# Logs
docker-compose -f docker/docker-compose.prod.yml logs -f

# Parar
docker-compose -f docker/docker-compose.prod.yml down
```

Acesse: http://localhost:7860

### Otimizacoes de Producao

O `Dockerfile.prod` ja inclui:
- Multi-stage build (imagem menor)
- Non-root user (seguranca)
- Health checks
- Cache otimizado

---

## 4. VPS/Cloud (DigitalOcean, AWS, etc)

### Pre-requisitos
- VPS com Ubuntu 22.04+
- 2GB RAM minimo (4GB recomendado)
- Docker instalado

### Setup no VPS

```bash
# SSH no servidor
ssh user@seu-servidor.com

# Instalar Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Instalar Docker Compose
sudo apt install docker-compose-plugin

# Clonar repositorio
git clone https://github.com/guifav/rag_template
cd rag_template

# Configurar .env
cp .env.example .env
nano .env  # Configure variaveis

# Deploy
docker-compose -f docker/docker-compose.prod.yml up -d

# Configurar nginx (opcional)
sudo apt install nginx
# Configure reverse proxy para porta 7860
```

### Nginx Config (Opcional)

```nginx
server {
    listen 80;
    server_name seu-dominio.com;

    location / {
        proxy_pass http://localhost:7860;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 5. GitHub (CI/CD Automatico)

O projeto ja inclui GitHub Actions configurados!

### O que esta automatizado:

#### CI (Continuous Integration)
- Roda em PRs e pushes
- Executa testes
- Verifica linting (ruff + black)
- Type checking (mypy)

Ver: [.github/workflows/ci.yml](.github/workflows/ci.yml)

#### CD (Continuous Deployment)
- Deploy automatico para Hugging Face Spaces
- Acionado em push para `main`

Ver: [.github/workflows/cd.yml](.github/workflows/cd.yml)

### Configurar GitHub Secrets

1. Va para Settings → Secrets and variables → Actions
2. Adicione:

```
HF_TOKEN=seu_token_hf
HF_USERNAME=seu_usuario_hf
SPACE_NAME=rag-template
```

Agora cada push para `main` faz deploy automatico!

---

## Atualizações Futuras

Para fazer deploy de novas versões:

```bash
# Adicionar mudanças
git add .

# Commit com mensagem descritiva
git commit -m "feat: nova funcionalidade"

# Push para ambos
git push origin main
git push hf main
```

## Comandos Úteis

### Verificar remotes configurados
```bash
git remote -v
```

### Ver histórico de commits
```bash
git log --oneline
```

### Ver diferenças antes de commit
```bash
git diff
```

### Ver status de arquivos
```bash
git status
```

### Criar nova branch para features
```bash
git checkout -b feature/nome-da-feature
```

### Voltar para main
```bash
git checkout main
```

## Troubleshooting

### Erro: remote already exists
```bash
git remote remove origin
git remote add origin https://github.com/guifav/rag_template.git
```

### Erro: authentication failed
```bash
# Use Personal Access Token (PAT) ao invés de senha
# GitHub: Settings → Developer settings → Personal access tokens
```

### Erro no Hugging Face Spaces
1. Verifique os logs em: https://huggingface.co/spaces/guifav/rag_template/logs
2. Confirme que os Secrets estão configurados corretamente
3. Verifique se o `requirements.txt` está correto

## Arquivos Importantes para Deploy

- ✅ `README.md` - Com metadata YAML para HF Spaces
- ✅ `app.py` - Aplicação principal
- ✅ `requirements.txt` - Dependências Python
- ✅ `.gitignore` - Arquivos a ignorar
- ✅ `.env.example` - Exemplo de configuração
- ✅ Pasta `src/` - Código backend
- ✅ Pasta `ui/` - Componentes de interface
- ✅ Pasta `docs/` - Documentação

## Checklist de Deploy

- [ ] Verificar que `.env` está em `.gitignore` (não fazer commit de secrets)
- [ ] Atualizar links no `README.md`
- [ ] Atualizar links no `app.py` footer
- [ ] Testar localmente antes do push
- [ ] Fazer commit com mensagem descritiva
- [ ] Push para GitHub
- [ ] Push para Hugging Face
- [ ] Configurar Secrets no HF Spaces
- [ ] Verificar logs e testar app no HF Spaces

## Links Importantes

- **GitHub Repo**: https://github.com/guifav/rag_template
- **HF Space**: https://huggingface.co/spaces/guifav/rag_template
- **HF Space Settings**: https://huggingface.co/spaces/guifav/rag_template/settings
- **Supabase Project**: https://supabase.com/dashboard/project/wwgxrzlisyqjovmlbjwt