Backend Deployment

Overview

This guide walks you through deploying the FitAiid backend API to Railway, a modern cloud platform that provides zero-config infrastructure for Node.js applications.

Estimated Time: 15 minutes
Difficulty: ⭐⭐ (Very Easy)

Prerequisites

Code on GitHub

Ensure your code is pushed to a GitHub repository with the backend in the backend/ directory.

MongoDB Atlas Ready

Your MongoDB Atlas cluster should be created and connection string available.

Environment Variables

Have all required API keys and credentials ready (see Environment Variables).

Railway Setup

1. Create Railway Account

Navigate to railway.app and click “Start for free”

Connect GitHub

Choose GitHub as your login method and authorize Railway to access your repositories.

Verify Account

Complete the verification process. You’ll receive $5 in free credits per month.

2. Create New Project

New Project

In your Railway dashboard, click “New Project”

Deploy from GitHub

Select “Deploy from GitHub repo” and choose your FitAidd repository

Configure Root Directory

IMPORTANT: Set the Root Directory to backend/This tells Railway to only deploy the backend folder, not the entire monorepo.

Enable Auto-Deploy

Toggle Auto-deploy to ON so Railway automatically deploys on every GitHub push to main branch.

If you forget to set the Root Directory, Railway will try to deploy the entire repository and fail. Always specify backend/ as the root.

Configure Environment Variables

Railway needs access to your environment variables to connect to external services.

Add Variables in Railway Dashboard

In your Railway project, navigate to the Variables tab
Add each variable from the list below
Click “Add Variable” after each entry

Required Environment Variables

# Server Configuration
PORT=5000
NODE_ENV=production

# Database
MONGODB_URI=mongodb+srv://username:[email protected]/FitAiid?retryWrites=true&w=majority

# JWT Authentication
JWT_SECRET=your-super-secure-jwt-secret-minimum-32-characters
JWT_EXPIRES_IN=24h

# Firebase Admin SDK (paste entire JSON)
FIREBASE_ADMIN_SDK={"type":"service_account","project_id":"...","private_key":"..."}

# OpenAI API
OPENAI_API_KEY=sk-proj-...

# Stripe Payments
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Email (Gmail App Password)
EMAIL_USER=[email protected]
EMAIL_PASS=your-app-specific-password

# Web Push Notifications (VAPID)
VAPID_PUBLIC_KEY=BH5NRoA1tucvywFDHTef...
VAPID_PRIVATE_KEY=iYatNX1EcokCuw3ZNs4dg...
VAPID_EMAIL=mailto:[email protected]

# CORS Origins (comma-separated)
CORS_ORIGINS=https://fitaiid.vercel.app,http://localhost:3000

See the complete Environment Variables guide for details on obtaining each credential.

MongoDB Atlas Network Configuration

Critical Step: Railway uses dynamic IPs, so you must whitelist all IPs in MongoDB Atlas.

Open MongoDB Atlas

Network Access

Go to Network Access in the left sidebar

Add IP Address

Click “Add IP Address” and enter:

IP Address: 0.0.0.0/0
Description: “Railway Production (All IPs)“

Using 0.0.0.0/0 allows access from any IP. This is required for Railway but ensure your MongoDB credentials are secure.

Confirm

Click “Confirm” and wait 1-2 minutes for changes to propagate.

Deploy to Railway

Trigger Deployment

After adding all environment variables, Railway will automatically start building your application.

Monitor Build Logs

Click on Deployments → Select the active deployment → View LogsYou should see:

npm install --omit=dev
Building application...
✅ Build successful
Starting server...
🚀 Server running on port 5000
✅ MongoDB Atlas connected

Get Your URL

Once deployed, Railway generates a public URL:

https://fitaiid-api.railway.app

Copy this URL - you’ll need it for the frontend configuration.

Backend Architecture

Dockerfile Configuration

Railway automatically detects and uses your Dockerfile:

# Use lightweight Node.js image
FROM node:18-slim

# Create working directory
WORKDIR /app

# Copy dependency files
COPY package*.json ./

# Install production dependencies only
RUN npm install --omit=dev

# Copy application code
COPY . .

# Expose port
EXPOSE 5000

# Start server
CMD ["node", "src/server.js"]

Database Connection

The backend uses Mongoose with optimized connection settings:

backend/src/config/database.js

const mongoose = require('mongoose');

const connectDB = async () => {
  const options = {
    maxPoolSize: 10,                // Max 10 concurrent connections
    serverSelectionTimeoutMS: 5000, // 5 second timeout
    socketTimeoutMS: 45000,         // 45 second socket timeout
    family: 4                       // Use IPv4
  };

  const conn = await mongoose.connect(process.env.MONGODB_URI, options);
  
  console.log('✅ MongoDB Atlas connected');
  console.log(`📍 Host: ${conn.connection.host}`);
  console.log(`🗃️  Database: ${conn.connection.name}`);
};

Verify Deployment

Test API Health

Open your browser and test the API endpoint:

https://fitaiid-api.railway.app/api/estadisticas/69a05da571820e5d373c8a21

Expected Response
Error Response

{
  "error": "Token no proporcionado",
  "code": 401
}

This is correct! The 401 error means the API is working but requires authentication.

Cannot GET /api/estadisticas

This indicates a routing issue. Check Railway logs for errors.

Test MongoDB Connection

Check Railway logs for MongoDB connection confirmation:

✅ MongoDB Atlas connected successfully
📍 Host: cluster0.voa5ykf.mongodb.net
🗃️  Database: FitAiid

Troubleshooting

Build fails with 'Module not found'

Cause: Missing dependency in package.jsonSolution:

Check Railway build logs for the missing module
Add to package.json dependencies:

npm install <missing-module> --save

Commit and push to GitHub

Cannot connect to MongoDB

Cause: IP not whitelisted or incorrect connection stringSolution:

Verify MongoDB Atlas Network Access has 0.0.0.0/0
Check MONGODB_URI format:

mongodb+srv://username:[email protected]/FitAiid

Ensure username/password don’t contain special characters (URL encode if needed)

Railway deployment stuck

Cause: Build timeout or memory limit exceededSolution:

Check Railway logs for timeout errors
Optimize dependencies by removing unused packages
Use npm ci instead of npm install for faster builds
Consider upgrading Railway plan for more resources

CORS errors from frontend

Cause: Frontend URL not in CORS whitelistSolution:

Add your Vercel URL to Railway environment variables:

CORS_ORIGINS=https://fitaiid.vercel.app,http://localhost:3000

Update backend/src/app.js CORS config:

const corsOptions = {
  origin: process.env.CORS_ORIGINS.split(','),
  credentials: true
};
app.use(cors(corsOptions));

Environment variables not loading

Cause: Variables not saved or deployment not restartedSolution:

Go to Railway Variables tab
Verify all variables are present
Click Redeploy to restart with new variables
Check logs for “undefined” errors

Post-Deployment Tasks

Copy Railway URL

Save your Railway URL for frontend configuration:

https://fitaiid-api.railway.app

Test All Endpoints

Use Swagger documentation at:

https://fitaiid-api.railway.app/api-docs

Monitor Performance

Set up monitoring in Railway Dashboard → Metrics to track:

CPU usage
Memory consumption
Request latency
Error rates

Configure Custom Domain (Optional)

Add a custom domain in Railway Settings → Domains:

api.fitaiid.com → fitaiid-api.railway.app

Next Steps

Deploy Frontend

Now that your backend is live, deploy the frontend to Vercel and connect it to your Railway API.

Getting Started

Core Features

User Guide

Deployment

Backend Deployment

Overview

Prerequisites

Railway Setup

1. Create Railway Account

2. Create New Project

Configure Environment Variables

Add Variables in Railway Dashboard

MongoDB Atlas Network Configuration

Deploy to Railway

Backend Architecture

Dockerfile Configuration

Database Connection

Verify Deployment

Test API Health

Test MongoDB Connection

Troubleshooting

Post-Deployment Tasks

Next Steps

Deploy Frontend

Build docs developers (and LLMs) love

Getting Started

Core Features

User Guide

Deployment

​Overview

​Prerequisites

​Railway Setup

​1. Create Railway Account

​2. Create New Project

​Configure Environment Variables

​Add Variables in Railway Dashboard

​MongoDB Atlas Network Configuration

​Deploy to Railway

​Backend Architecture

​Dockerfile Configuration

​Database Connection

​Verify Deployment

​Test API Health

​Test MongoDB Connection

​Troubleshooting

​Post-Deployment Tasks

​Next Steps

Deploy Frontend

Build docs developers (and LLMs) love

Overview

Prerequisites

Railway Setup

1. Create Railway Account

2. Create New Project

Configure Environment Variables

Add Variables in Railway Dashboard

MongoDB Atlas Network Configuration

Deploy to Railway

Backend Architecture

Dockerfile Configuration

Database Connection

Verify Deployment

Test API Health

Test MongoDB Connection

Troubleshooting

Post-Deployment Tasks

Next Steps