Tech Stack Advisor - Code Viewer

# Railway Deployment Guide

## Overview

This guide walks through deploying the Tech Stack Advisor to Railway as a **single unified service** that serves both the REST API and the Modern Web UI (HTML/CSS/JavaScript) from the FastAPI backend.

---

## Prerequisites

- GitHub account
- Railway account (sign up at https://railway.app)
- Repository pushed to GitHub (private or public)

---

## Deployment Steps

### 1. Push Code to GitHub

```bash
# Initialize git (if not already done)
git init
git add .
git commit -m "Initial commit"

# Create private GitHub repo and push
git remote add origin https://github.com/YOUR_USERNAME/tech-stack-advisor.git
git branch -M main
git push -u origin main
```

---

### 2. Deploy Application

#### A. Create Railway Project

1. Go to https://railway.app/new
2. Click **"Deploy from GitHub repo"**
3. Select your repository (grant Railway access if first time)
4. Railway will create a project

#### B. Configure Service

1. In Railway dashboard, click your project
2. Click **"Settings"**
3. Set **Build Command**: (leave empty, auto-detected)
4. Set **Start Command**: `python -m backend.src.api.main`
5. Click **"Variables"** tab
6. Add environment variables:

```
ANTHROPIC_API_KEY=sk-ant-api03-your-actual-key-here
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-qdrant-key-or-leave-empty
ENVIRONMENT=production
LOG_LEVEL=INFO
PORT=8000
SECRET_KEY=your-secret-key-for-jwt
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=https://your-app.up.railway.app/auth/google/callback
```

7. Click **"Deploy"**
8. Wait for deployment (2-3 minutes)
9. **Copy the public URL** (e.g., `your-app-production-xxxx.up.railway.app`)
10. **Update `GOOGLE_REDIRECT_URI`** with your actual Railway URL

---

### 3. Test Deployment

1. Open your Railway URL: `https://your-app.up.railway.app`
2. You'll be redirected to login page
3. Register a new account at `/register.html`
4. Log in with your credentials
5. Submit a test query: `"Building a chat app for 10K users"`
6. Verify all 4 agent tabs show results

---

## Docker-Based Deployment

### Why Docker?

This project uses Docker for deployment to solve Python version compatibility issues between local development and Railway's build environment:

**Problem**:
- Local development may use Python 3.11.6
- Railway's nixpacks build system might try to use Python 3.13+ (which may not be available as precompiled binaries)
- This mismatch can cause build failures

**Solution**:
The `Dockerfile` explicitly specifies Python 3.11-slim, ensuring consistent environments:

```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Environment variables for Python
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_NO_CACHE_DIR=1

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose port
EXPOSE 8000

# Health check for container orchestration
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD python -c "import requests; requests.get('http://localhost:8000/health', timeout=5)"

# Run application
CMD ["python", "-m", "backend.src.api.main"]
```

**Benefits**:
1. **Reproducible builds** - Same Python version everywhere
2. **Faster deployments** - Docker layer caching speeds up subsequent builds
3. **Health checks** - Built-in health monitoring for Railway
4. **Production-ready** - Optimized multi-stage build with minimal image size

**Railway Auto-Detection**:
Railway automatically detects the Dockerfile and uses it for builds. No additional configuration needed!

**Important Notes**:
- **Remove Custom Start Commands**: If you have a custom start command in Railway dashboard settings, remove it to let the Dockerfile CMD take precedence
- **Remove Procfile**: The Procfile is not needed when using Docker
- **Railway Command Precedence**: Custom Start Command > Procfile > Dockerfile CMD

---

## Environment Variables Reference

### Application (.env equivalent)

| Variable | Required | Example | Description |
|----------|----------|---------|-------------|
| `ANTHROPIC_API_KEY` | ✅ Yes | `sk-ant-api03-...` | Anthropic Claude API key |
| `QDRANT_URL` | No | `http://localhost:6333` | Qdrant vector store URL |
| `QDRANT_API_KEY` | No | `your-key` | Qdrant API key (if using cloud) |
| `ENVIRONMENT` | No | `production` | Environment name |
| `LOG_LEVEL` | No | `INFO` | Logging level |
| `PORT` | Auto | `8000` | Railway auto-sets this |
| `SECRET_KEY` | ✅ Yes | `your-secret-key` | JWT secret key |
| `GOOGLE_CLIENT_ID` | Optional | `xxx.apps.googleusercontent.com` | Google OAuth client ID |
| `GOOGLE_CLIENT_SECRET` | Optional | `your-secret` | Google OAuth client secret |
| `GOOGLE_REDIRECT_URI` | Optional | `https://your-app.up.railway.app/auth/google/callback` | OAuth callback URL |

---

## Custom Domain (Optional)

### Add Custom Domain to Application

1. Go to your service → **"Settings"** → **"Domains"**
2. Click **"+ Add Domain"**
3. Enter your domain: `techstack.yourdomain.com`
4. Add CNAME record in your DNS:
   ```
   CNAME techstack → your-app.up.railway.app
   ```
5. Wait for DNS propagation (5-60 minutes)
6. Railway automatically provisions SSL certificate
7. Update `GOOGLE_REDIRECT_URI` environment variable with your custom domain

---

## Monitoring & Logs

### View Logs

1. Go to service in Railway
2. Click **"Deployments"**
3. Click latest deployment
4. View real-time logs

### Check Metrics

1. Go to service → **"Metrics"**
2. View CPU, Memory, Network usage

---

## Cost Estimation

Railway pricing (as of 2024):
- **Free Trial**: $5 credit (500 execution hours/month)
- **Hobby Plan**: $5/month includes:
  - Unlimited execution hours
  - 100 GB bandwidth
  - Single unified service

**Expected cost for this app:**
- Single service running 24/7
- ~720 hours/month (exceeds free tier)
- **Total: $5/month (Hobby plan required)**

---

## Troubleshooting

### Application won't load / Login page not appearing

1. Check service is deployed and running in Railway dashboard
2. Verify environment variables are set correctly
3. Check deployment logs for errors
4. Test health endpoint: `curl https://your-app.up.railway.app/health`
5. Check `SECRET_KEY` is set for JWT authentication

### Application crashes on startup

1. Check logs for errors
2. Verify `ANTHROPIC_API_KEY` is set correctly
3. Check Python version (Docker uses 3.11-slim automatically)
4. Verify all dependencies installed
5. Ensure Dockerfile is present in repository root
6. **Remove custom start commands** from Railway dashboard (let Dockerfile CMD handle it)

### "Module not found" errors

1. Check `requirements.txt` includes all dependencies
2. Verify Railway detected Python correctly
3. Check build logs for pip install errors

### High costs

1. Check metrics for unexpected usage
2. Verify no infinite loops in code
3. Consider scaling down if not in use
4. Use Railway's auto-sleep feature (hobby plan)

---

## Updates & Redeployment

Railway automatically redeploys when you push to GitHub:

```bash
# Make changes
git add .
git commit -m "Update feature X"
git push origin main

# Railway automatically:
# 1. Detects push
# 2. Builds new image
# 3. Deploys (zero-downtime)
```

---

## Useful Railway CLI Commands

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

# Login
railway login

# Link to project
railway link

# View logs
railway logs

# Run command in Railway environment
railway run python scripts/test.py

# Open dashboard
railway open
```

---

## Security Best Practices

1. **Never commit `.env` file** (already in `.gitignore`)
2. **Use Railway environment variables** for secrets
3. **Rotate API keys** regularly
4. **Enable HTTP basic auth** in Railway settings (optional)
5. **Monitor usage** to detect anomalies

---

## Support & Resources

- **Railway Docs**: https://docs.railway.app
- **Railway Discord**: https://discord.gg/railway
- **This Project**: [Add your GitHub URL]
- **Issues**: [Add your GitHub issues URL]

---

## Quick Commands Reference

```bash
# Test locally before deploying
./run_app.sh

# Push to GitHub (triggers Railway deploy)
git push origin main

# View Railway logs
railway logs

# Open Railway dashboard
railway open

# Check application health
curl https://your-app.up.railway.app/health

# Test login (requires account)
# Visit https://your-app.up.railway.app/register.html first

# Test recommendation endpoint (requires JWT token)
curl -X POST https://your-app.up.railway.app/recommend \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"query":"Test query"}'
```

---

**Status:** Ready for deployment
**Estimated Setup Time:** 15-20 minutes
**Monthly Cost:** $5-10
**Scalability:** Handles 100-1000 requests/day easily

Deploy now at: https://railway.app 🚀