Spaces:

guifav
/

rag_template

Sleeping

# 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

Va para Settings do Space
Adicione em "Repository secrets":

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

Opcional:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Veja guia completo: 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

2. Railway

Pre-requisitos

Conta no Railway
GitHub account

Passo a Passo

2.1. Criar Projeto

Acesse railway.app
"New Project" → "Deploy from GitHub repo"
Selecione repositorio rag_template

2.2. Adicionar PostgreSQL

No projeto, clique "+ New"
"Database" → "Add PostgreSQL"
Railway cria banco automaticamente

2.3. Habilitar pgvector

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

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

3. Docker Local/Producao

Pre-requisitos

Docker e Docker Compose instalados
Database externo OU use o PostgreSQL no compose

Opcao A: Com Database Externo

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

# 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

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

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

CD (Continuous Deployment)

Deploy automatico para Hugging Face Spaces
Acionado em push para main

Ver: .github/workflows/cd.yml

Configurar GitHub Secrets

Va para Settings → Secrets and variables → Actions
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:

# 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

git remote -v

Ver histórico de commits

git log --oneline

Ver diferenças antes de commit

git diff

Ver status de arquivos

git status

Criar nova branch para features

git checkout -b feature/nome-da-feature

Voltar para main

git checkout main

Troubleshooting

Erro: remote already exists

git remote remove origin
git remote add origin https://github.com/guifav/rag_template.git

Erro: authentication failed

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

Erro no Hugging Face Spaces

Verifique os logs em: https://huggingface.co/spaces/guifav/rag_template/logs
Confirme que os Secrets estão configurados corretamente
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