docs/RAILWAY_SETUP.md

# Configuracao Railway

Railway e uma plataforma de deploy que oferece PostgreSQL com pgvector e integracao facil com GitHub.

## Vantagens

- Deploy com um clique
- PostgreSQL + pgvector pre-configurado
- Integracao com GitHub (deploy automatico)
- Logs e monitoring integrados
- Ambientes de preview para PRs
- CLI poderoso

---

## Setup Passo a Passo

### 1. Criar Conta

1. Acesse [railway.app](https://railway.app)
2. Clique em "Start a New Project"
3. Faca login com GitHub (recomendado)

### 2. Criar Projeto

#### Opcao A: Projeto Vazio + PostgreSQL

1. No dashboard, clique em "+ New Project"
2. Escolha "Empty Project"
3. Nomeie seu projeto: `rag-template`

#### Opcao B: Deploy do GitHub (Recomendado)

1. Clique em "+ New Project"
2. Escolha "Deploy from GitHub repo"
3. Selecione o repositorio `rag_template`
4. Railway detectara automaticamente que e um app Python

### 3. Adicionar PostgreSQL

1. No seu projeto, clique em "+ New"
2. Escolha "Database" → "Add PostgreSQL"
3. Railway criara um banco PostgreSQL automaticamente

### 4. Habilitar pgvector

Railway usa PostgreSQL padrao. Precisamos habilitar a extensao pgvector:

#### Via Railway CLI

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

# Login
railway login

# Entre no projeto
railway link

# Conecte ao PostgreSQL
railway run psql $DATABASE_URL

# No psql, execute:
CREATE EXTENSION IF NOT EXISTS vector;
\q
```

#### Via Connection direto (alternativa)

```bash
# Copie DATABASE_URL do Railway
# Conecte usando psql local
psql "postgresql://postgres:...@containers.railway.app:5432/railway"

# Execute:
CREATE EXTENSION vector;
```

### 5. Obter Variaveis de Ambiente

No dashboard do Railway:

1. Clique no servico PostgreSQL
2. Va para "Variables"
3. Copie as variaveis necessarias:

```env
DATABASE_URL=postgresql://postgres:...@containers-us-west-XXX.railway.app:5432/railway
PGHOST=containers-us-west-XXX.railway.app
PGPORT=5432
PGUSER=postgres
PGPASSWORD=...
PGDATABASE=railway
```

### 6. Configurar Aplicacao

Se deploying no Railway:

1. Clique no servico da aplicacao
2. Va para "Variables"
3. Adicione:

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

**Dica**: `${{Postgres.DATABASE_URL}}` referencia automaticamente o DATABASE_URL do servico PostgreSQL.

### 7. Configurar Local

Para desenvolvimento local:

```bash
# .env
DATABASE_URL=postgresql://postgres:...@containers-us-west-XXX.railway.app:5432/railway
HF_TOKEN=seu_token_aqui
```

---

## Deploy Automatico

### Conectar GitHub

1. No servico da aplicacao, va para "Settings"
2. Em "Source", conecte seu repositorio GitHub
3. Configure:
   - Branch: `main`
   - Build command: (Railway detecta automaticamente)
   - Start command: `python app.py`

### Configurar Build

Se necessario, crie um `railway.toml`:

```toml
[build]
builder = "nixpacks"

[deploy]
startCommand = "python app.py"
healthcheckPath = "/"
healthcheckTimeout = 100
restartPolicyType = "on_failure"
```

Ou use `Procfile`:

```
web: python app.py
```

### Deploy Triggers

Agora, a cada push para `main`:
1. Railway detecta a mudanca
2. Faz build automatico
3. Deploy da nova versao
4. Mantem logs acessiveis

---

## Ambientes de Preview

Railway pode criar ambientes de preview para cada PR:

1. Va para "Settings" do projeto
2. Habilite "PR Deploys"
3. Cada PR recebera sua propria URL temporaria

Util para testar mudancas antes do merge!

---

## Limites Free Tier

Railway oferece **$5 de credito gratuito por mes**:

| Recurso | Consumo |
|---------|---------|
| PostgreSQL | ~$5/mes (24/7) |
| App (512MB RAM) | ~$5/mes (24/7) |
| Bandwidth | $0.10/GB |

**Estimativa**: Com $5, voce consegue:
- PostgreSQL 24/7 (~$5)
- OU App + PostgreSQL com ~50% uptime
- OU Usar apenas para desenvolvimento (pausar quando nao usar)

**Dicas para economizar**:

1. **Desenvolvimento**: Use PostgreSQL do Railway, mas rode app localmente
2. **Producao**: Upgrade para plano Hobby ($5/mes) ou Pro ($20/mes)
3. **Pausar servicos**: Railway pode pausar servicos sem uso

---

## Monitoramento

### Dashboard

O dashboard do Railway mostra:
- CPU e memoria em tempo real
- Logs de deploy e runtime
- Metricas de rede
- Uso de creditos

### Logs

```bash
# Via CLI
railway logs

# Via dashboard
# Clique no servico → "Logs"
```

### Metricas

```bash
# Via CLI
railway status

# Via dashboard
# Clique no servico → "Metrics"
```

---

## CLI Avancado

### Comandos Uteis

```bash
# Ver status
railway status

# Ver logs em tempo real
railway logs -f

# Executar comandos no contexto do Railway
railway run python manage.py

# Abrir shell no PostgreSQL
railway run psql $DATABASE_URL

# Backup
railway run pg_dump $DATABASE_URL > backup.sql

# Conectar localmente usando variaveis do Railway
railway run python app.py
```

### Variables

```bash
# Listar variaveis
railway variables

# Adicionar variavel
railway variables add HF_TOKEN=seu_token

# Deletar variavel
railway variables delete OLD_VAR
```

---

## Configuracoes de Producao

### Health Checks

Railway pode fazer health checks automaticos:

```toml
# railway.toml
[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 100
```

Adicione endpoint de health no app:

```python
# app.py
@app.get("/health")
def health():
    return {"status": "healthy"}
```

### Restart Policy

```toml
[deploy]
restartPolicyType = "on_failure"
restartPolicyMaxRetries = 3
```

### Resource Limits

No dashboard, configure:
- Memory: 512MB (free) ate 32GB (paid)
- CPU: Shared (free) ate dedicated (paid)

---

## Troubleshooting

### Erro: "Unable to connect to database"

Verifique:
1. DATABASE_URL esta correto
2. Variavel `${{Postgres.DATABASE_URL}}` esta configurada
3. PostgreSQL esta rodando (veja Metrics)

### Erro: "pgvector extension not found"

Execute:
```bash
railway run psql $DATABASE_URL -c "CREATE EXTENSION vector;"
```

### Build Failing

Verifique:
1. `requirements.txt` esta completo
2. Python version compativel (configure em Settings)
3. Logs de build para erros especificos

### App Crashing

1. Veja logs: `railway logs`
2. Verifique variaveis de ambiente
3. Teste localmente: `railway run python app.py`

---

## Migracao

### De Local para Railway

```bash
# Dump local
pg_dump -h localhost -U postgres ragdb > dump.sql

# Restore no Railway
railway run psql $DATABASE_URL < dump.sql
```

### De Outro Provider

```bash
# De Supabase/Neon
pg_dump "postgresql://..." > dump.sql

# Para Railway
railway run psql $DATABASE_URL < dump.sql
```

---

## Upgrade de Plano

| Plano | Credito/mes | Recursos | Preco |
|-------|-------------|----------|-------|
| Free | $5 | Compartilhado | $0 |
| Hobby | $5 + $5 uso | Dedicado leve | $5/mes |
| Pro | $20 + uso | Dedicado completo | $20/mes |

**Quando fazer upgrade**:
- App precisa rodar 24/7
- Mais de 512MB RAM
- Suporte prioritario

Veja: [railway.app/pricing](https://railway.app/pricing)

---

## Integracao com GitHub Actions

Voce pode usar Railway CLI no GitHub Actions:

```yaml
# .github/workflows/deploy.yml
name: Deploy to Railway

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Railway CLI
        run: npm i -g @railway/cli
      - name: Deploy
        run: railway up
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
```

---

## Database Branching

Railway ainda nao tem branching nativo como Neon, mas voce pode:

1. **Criar multiplos projetos**:
   - `rag-template-prod`
   - `rag-template-dev`

2. **Usar Railway Environments**:
   - production
   - staging
   - development

Cada environment pode ter suas proprias variaveis.

---

## Recursos Adicionais

- [Documentacao Railway](https://docs.railway.app)
- [Railway CLI](https://docs.railway.app/develop/cli)
- [Deploy Guide](https://docs.railway.app/deploy/deployments)
- [Discord](https://discord.gg/railway)

---

## Comparacao com Outros Provedores

Veja [DATABASE_COMPARISON.md](DATABASE_COMPARISON.md) para comparar Railway com Supabase, Neon e outros.

---

**Proximo passo**: [Voltar ao README](../README.md) ou configurar deploy!