Skip to main content

​
Overview

Railway is the recommended platform for hosting the Nectr FastAPI backend. This guide walks you through deploying the backend with automatic migrations and environment configuration.
The backend runs on Railway while the frontend deploys separately to Vercel. See Vercel Deployment for frontend setup.

​
Prerequisites

Before deploying to Railway, ensure you have:
  • A Railway account
  • A forked copy of the Nectr repository
  • API keys for required services (see below)

​
Required API Keys

1

Anthropic API Key

Get your API key from console.anthropic.com
ANTHROPIC_API_KEY=sk-ant-...
2

GitHub OAuth App

Create a new OAuth App at github.com/settings/developersSet the Authorization callback URL to:
https://your-project.up.railway.app/auth/github/callback
Save these credentials:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
3

GitHub Personal Access Token

Create a classic token at github.com/settings/tokens with repo scope.This is used to post PR review comments.
GITHUB_PAT=ghp_...
4

Secret Key

Generate a secure secret key for JWT signing and token encryption:
python -c "import secrets; print(secrets.token_hex(32))"

SECRET_KEY=your-generated-secret-here
5

Neo4j Database

Sign up for a free Neo4j AuraDB instance at neo4j.com/cloud
NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=...
6

Mem0 API Key

Get your API key from mem0.ai
MEM0_API_KEY=m0-...

​
Deployment Steps

1

Create New Project

  1. Log in to Railway
  2. Click New Project
  3. Select Deploy from GitHub repo
  4. Connect your GitHub account and select your Nectr fork
2

Add PostgreSQL Database

  1. In your Railway project, click New
  2. Select Database → PostgreSQL
  3. Railway will automatically provision a PostgreSQL database
  4. Copy the DATABASE_URL from the database service
3

Configure Environment Variables

In your Railway service settings, add all required environment variables:
# AI
ANTHROPIC_API_KEY=sk-ant-...

# GitHub OAuth + API
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_PAT=ghp_...

# Database (automatically set by Railway)
DATABASE_URL=postgresql+asyncpg://...

# Auth
SECRET_KEY=your-generated-secret

# Neo4j
NEO4J_URI=neo4j+s://xxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=...

# Mem0
MEM0_API_KEY=m0-...

# App URLs (update after deployment)
BACKEND_URL=https://your-project.up.railway.app
FRONTEND_URL=https://your-app.vercel.app

# Environment
APP_ENV=production
LOG_LEVEL=INFO
4

Configure Build Settings

Railway automatically detects the build configuration from railway.json:
railway.json
{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE",
    "dockerfilePath": "Dockerfile"
  },
  "deploy": {
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}
The Dockerfile handles the build process:
Dockerfile
FROM python:3.14-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD uvicorn app.main:app --host 0.0.0.0 --port $PORT
5

Deploy

  1. Railway will automatically start building and deploying
  2. Monitor the deployment logs in the Railway dashboard
  3. Database migrations run automatically on startup via Alembic
  4. Once deployed, copy your Railway app URL (e.g., https://nectr-production.up.railway.app)
6

Update OAuth Callback URL

Return to your GitHub OAuth App settings and update the Authorization callback URL:
https://your-actual-project.up.railway.app/auth/github/callback
7

Update Environment URLs

Update these environment variables in Railway with your actual deployment URL:
BACKEND_URL=https://your-project.up.railway.app
FRONTEND_URL=https://your-app.vercel.app

​
Verify Deployment

Test your deployment with these endpoints: 
curl https://your-project.up.railway.app/health

​
Automatic Migrations

Database migrations run automatically on every deployment via the app.main:app lifespan context. The migration process:
  1. Connects to PostgreSQL using DATABASE_URL
  2. Runs all pending Alembic migrations
  3. Initializes Neo4j schema (constraints + indexes)
  4. Starts the FastAPI server
You can view migration logs in the Railway deployment console to ensure they complete successfully.

​
Continuous Deployment

Railway automatically deploys on every push to your default branch:
  1. Push changes to GitHub
  2. Railway detects the commit
  3. Builds new Docker image
  4. Runs migrations
  5. Deploys with zero-downtime
Ensure your main branch is stable before pushing, as Railway will auto-deploy immediately.

​
Troubleshooting

Symptom: App fails to start with asyncpg connection errorsSolution:
  1. Verify DATABASE_URL is set correctly
  2. Ensure the URL uses postgresql+asyncpg:// prefix
  3. Check that the Railway PostgreSQL service is running
  4. Verify network connectivity between services
Symptom: Alembic migrations fail during startupSolution:
  1. Check Railway logs for specific migration errors
  2. Verify database schema matches expected state
  3. Manually run migrations if needed:
railway run alembic upgrade head
Symptom: Neo4j health check failsSolution:
  1. Verify NEO4J_URI uses neo4j+s:// prefix for secure connections
  2. Check credentials are correct
  3. Ensure Neo4j AuraDB instance is running
  4. Verify network access from Railway to Neo4j
Symptom: Uvicorn fails to bind to portSolution: Railway automatically sets the PORT environment variable. The Procfile uses it:
web: uvicorn app.main:app --host 0.0.0.0 --port $PORT
Do not hardcode the port number.

​
Monitoring & Logs

​
View Logs

Access real-time logs in the Railway dashboard:
  1. Open your project
  2. Click on the service
  3. Navigate to Deployments → View Logs

​
Set Log Level

Control log verbosity with the LOG_LEVEL environment variable: 
LOG_LEVEL=INFO    # production (default)
LOG_LEVEL=DEBUG   # development
LOG_LEVEL=ERROR   # minimal logging

​
Scaling

Railway handles scaling automatically, but you can configure:
  1. Restart Policy: Already set to ON_FAILURE with 10 retries
  2. Resource Limits: Adjust in Railway project settings
  3. Region: Select closest to your users for lower latency

​
Cost Considerations

Railway pricing is based on usage:
  • Hobby Plan: $5/month + usage-based
  • PostgreSQL: Included in usage
  • Bandwidth: Pay-as-you-go
Railway offers a free trial with $5 credit. Monitor your usage in the Railway dashboard.

​
Next Steps

Deploy Frontend

Deploy the Next.js frontend to Vercel

Configure GitHub App

Set up GitHub OAuth and webhooks

Build docs developers (and LLMs) love

Get started for freeTalk to us