Hugging Face's logo

Spaces:
guifav
/
rag_template
Sleeping

App Files Community
rag_template / docs /RAILWAY_SETUP.md
Guilherme Favaron
Sync: Complete project update (Phase 6) - API, Metadata, Eval, Docs
a686b1b
preview code
|
raw
history blame contribute delete
8.11 kB

A newer version of the Gradio SDK is available: 6.9.0

Upgrade

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

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

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

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

[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 

# Via CLI
railway logs

# Via dashboard
# Clique no servico → "Logs"

Metricas 

# Via CLI
railway status

# Via dashboard
# Clique no servico → "Metrics"

CLI Avancado

Comandos Uteis 

# 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 

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

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

Adicione endpoint de health no app:

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

Restart Policy 

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

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 

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

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

De Outro Provider 

# 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

Integracao com GitHub Actions

Voce pode usar Railway CLI no GitHub Actions:

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

Comparacao com Outros Provedores

Veja DATABASE_COMPARISON.md para comparar Railway com Supabase, Neon e outros.

Proximo passo: Voltar ao README ou configurar deploy!