resources_references/RAILWAY_SETUP_GUIDE.md

🚂 Railway Deployment Guide for TalimBot

📋 Overview

This guide will help you deploy your complete TalimBot application (Frontend + Backend) to Railway for free, making it accessible from anywhere.

✅ What We've Done (Preparation Complete!)

1. Restructured the Project

• ✅ Created backend/static/ folder
• ✅ Moved all frontend files (HTML, CSS, JS, Icons) to backend/static/
• ✅ Updated main.py to serve static files
• ✅ Updated data.js to use relative API paths for Railway

2. Updated FastAPI Configuration

Your backend/main.py now:

• Serves static files from backend/static/ folder
• Uses environment variable for OpenRouter API key
• Handles both frontend (HTML pages) and backend (API endpoints) from the same server
• Works seamlessly on Railway's deployment platform

3. Project Structure

talimbot/
├── .env                     # LOCAL ONLY - Contains your API key (NEVER commit this!)
├── .env.example             # Template for environment variables
├── .gitignore               # Ensures .env is not committed
├── Procfile                 # Tells Railway how to start the server
├── runtime.txt              # Specifies Python version
├── README.md                
├── RAILWAY_DEPLOYMENT.md    
├── backend/
│   ├── main.py              # ✅ UPDATED - Serves static files + API endpoints
│   ├── grouping_logic.py    
│   ├── requirements.txt     
│   ├── data/
│   │   └── students.json    
│   └── static/              # ✅ NEW - All frontend files
│       ├── index.html       
│       ├── assets/          # CSS and JS files
│       │   ├── css/
│       │   │   └── styles.css
│       │   └── js/
│       │       ├── data.js  # ✅ UPDATED - Uses relative API paths
│       │       └── grouping.js
│       ├── pages/           # All HTML pages
│       │   ├── login.html
│       │   ├── student-dashboard.html
│       │   ├── teacher-dashboard.html
│       │   ├── ams-questionnaire.html
│       │   ├── cooperative-questionnaire.html
│       │   └── group-view.html
│       └── Icons/           # Logo and icons

---

🚀 Deployment Steps

Step 1: Verify Local Setup

1. Create .env file (if you haven't already):

   # In the project root (talimbot/) folder
   echo OPENROUTER_API_KEY=sk-or-v1-your-actual-key-here > .env
   

2. Test locally:

   cd backend
   python main.py
   

3. Open browser to http://localhost:8000

   • You should see the index.html page
   • All pages should work (login, dashboards, questionnaires)
   • API calls should work (grouping, data saving)

---

Step 2: Commit Changes to GitHub

⚠️ IMPORTANT: Make sure .env is in .gitignore (it already is!)

# From the talimbot/ directory
git add .
git status  # Verify .env is NOT listed (should only see modified files)

git commit -m "Restructure project for Railway deployment - serve frontend from backend"
git push origin main

---

Step 3: Deploy to Railway

A. Sign Up / Log In

1. Go to railway.app
2. Click "Start a New Project"
3. Sign in with your GitHub account

B. Create New Project

1. Click "Deploy from GitHub repo"
2. Select your talimbot repository
3. Railway will automatically detect it's a Python project

C. Configure Environment Variables

1. In the Railway dashboard, go to your project
2. Click on the "Variables" tab
3. Click "+ New Variable"
4. Add:
   • Key: OPENROUTER_API_KEY
   • Value: sk-or-v1-your-actual-openrouter-api-key
5. Click "Add"

D. Verify Deployment Settings

Railway auto-detects settings from your files:

• ✅ Build Command: None needed (Python dependencies auto-installed)
• ✅ Start Command: From Procfile → cd backend && uvicorn main:app --host 0.0.0.0 --port $PORT
• ✅ Python Version: From runtime.txt → python-3.11.0

E. Deploy!

1. Click "Deploy"
2. Wait 2-3 minutes for deployment
3. Railway will show deployment logs
4. When complete, you'll see: ✅ "Deployment successful"

F. Get Your URL

1. In Railway dashboard, click "Settings" tab
2. Scroll to "Networking" section
3. Click "Generate Domain"
4. Copy your URL (e.g., https://talimbot-production-abc123.up.railway.app)

---

Step 4: Test Your Deployed Application

1. Open your Railway URL in a browser
2. Test all features:
   • ✅ Main page loads (index.html)
   • ✅ Login page works (/pages/login.html)
   • ✅ Student dashboard loads
   • ✅ Teacher dashboard loads
   • ✅ Questionnaires work (AMS, Cooperative)
   • ✅ Grouping functionality works
   • ✅ Data saves correctly

---

🔧 How It Works

Single Server Architecture

Railway runs ONE server that handles BOTH:

1. Frontend (Static Files):

   • GET / → Serves index.html
   • GET /pages/login.html → Serves login page
   • GET /assets/css/styles.css → Serves CSS
   • GET /assets/js/data.js → Serves JavaScript

2. Backend (API Endpoints):

   • POST /api/grouping → AI grouping logic
   • GET /api/students → Get all students
   • PUT /api/students/{id} → Update student
   • All other API routes in main.py

How Requests Are Routed

User Browser → Railway URL
              ↓
        FastAPI Server (main.py)
              ↓
    ┌─────────┴─────────┐
    ↓                   ↓
  /api/*            Everything else
(API Endpoints)     (Static Files)
    ↓                   ↓
grouping_logic.py   backend/static/
OpenRouter API        (HTML/CSS/JS)

Environment Variable Flow

Local Development:
.env file → load_dotenv() → os.getenv("OPENROUTER_API_KEY")

Railway Production:
Railway Variables → os.getenv("OPENROUTER_API_KEY")

---

📊 Monitoring & Management

View Logs

1. Go to Railway dashboard
2. Click on your project
3. Click "Deployments" tab
4. Click on the latest deployment
5. View real-time logs

Check Usage

• Railway free tier: $5 credit/month
• Your app should use: ~$2-3/month
• Monitor usage in "Usage" tab

Redeploy (After Code Changes)

1. Make changes locally
2. Test locally (python main.py)
3. Commit and push to GitHub:

   git add .
   git commit -m "Your changes"
   git push origin main
   

4. Railway auto-deploys within 1-2 minutes!

---

🆘 Troubleshooting

Problem: API calls fail (404 errors)

Solution: API routes must start with /api/

• ✅ Correct: POST /api/grouping
• ❌ Wrong: POST /grouping

Problem: Static files not loading (CSS/JS missing)

Solution:

1. Verify files are in backend/static/ folder
2. Check browser console for 404 errors
3. Ensure paths in HTML are relative (e.g., /assets/css/styles.css)

Problem: OpenRouter API errors

Solution:

1. Verify API key is correct in Railway Variables
2. Check you have credits in your OpenRouter account
3. View logs in Railway to see exact error message

Problem: Server won't start

Solution:

1. Check Railway logs for error messages
2. Verify requirements.txt has all dependencies
3. Ensure Procfile command is correct

---

🎯 Success Checklist

After deployment, verify:

• Railway URL loads the main page
• All navigation links work
• Login system works (student/teacher)
• Student dashboard loads
• Teacher dashboard loads
• AMS questionnaire works and saves
• Cooperative questionnaire works and saves
• AI grouping creates groups successfully
• Student data persists after refresh
• API calls complete without errors
• No console errors in browser DevTools

---

💡 Next Steps

Once deployed successfully:

1. Share the Railway URL with your teacher
2. Test from different devices (phone, tablet)
3. Monitor Railway dashboard for any errors
4. Keep your OpenRouter API key secure
5. Consider upgrading Railway plan if you exceed free tier

---

📞 Support Resources

• Railway Docs: https://docs.railway.app
• OpenRouter Docs: https://openrouter.ai/docs
• FastAPI Docs: https://fastapi.tiangolo.com
• Your Deployment Guide: RAILWAY_DEPLOYMENT.md

---

🎉 Congratulations!

Your TalimBot is now a real, independent website accessible from anywhere! 🚀

Your app URL: https://your-project.up.railway.app

Teachers and students can access it from:

• ✅ Home computers
• ✅ School computers
• ✅ Phones (any device with internet)
• ✅ Tablets

No need for localhost, no need for running Python locally - it's fully online! 🌐