Railway Deployment Guide

Step-by-step guide to deploy EpiPulse’s appointment booking system on Railway. Free hosting for your appointment platform.

Railway Deployment Guide

This guide walks you through deploying EpiPulse’s custom appointment booking system on Railway - a free, easy-to-use cloud hosting platform perfect for NGOs.

What is Railway?

Railway is a free hosting platform that: - ✅ Hosts your Node.js application - ✅ Provides free PostgreSQL database - ✅ Offers automatic deployments from GitHub - ✅ Includes free SSL/HTTPS certificate - ✅ Gives you $5 credit monthly - ✅ No credit card required initially

Alternative: You can also use the simpler Formspree solution for basic form submissions.

Why Use Railway?

Advantages

  • Complete Control: Your own server, your own data
  • Free: $5/month credit covers small NGO operations
  • Scalable: Grows with your organization
  • Easy to Update: Deploy changes in seconds
  • Database Included: PostgreSQL for patient records
  • Professional: Custom domain support

Disadvantages

  • Requires GitHub account and basic Git knowledge
  • Setup takes 30-45 minutes
  • Needs some technical understanding

Prerequisites

What You Need

  1. GitHub Account (free)
    • Sign up at github.com
    • Upload our appointment code
  2. Railway Account (free)
  3. Text Editor
    • VS Code (recommended, free)
    • Notepad++, Sublime Text, or any editor
  4. Git (optional but recommended)
    • Download from git-scm.com
    • Allows easy code synchronization

Step 1: Create GitHub Repository

Setup GitHub Repo

  1. Create GitHub Account

    • Go to github.com
    • Sign up with email
    • Verify email

  2. Create New Repository

    • Click “+” in top right
    • Select “New repository”
    • Name: epipulse-appointments
    • Description: “EpiPulse Online Appointment Booking System”
    • Select “Public”
    • Check “Add README”
    • Click “Create repository”

  3. Clone Repository to Your Computer

    git clone https://github.com/YOUR_USERNAME/epipulse-appointments.git
cd epipulse-appointments

Add Project Files

Copy these files to your repository folder:

1. package.json

{
  "name": "epipulse-appointments",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "pg": "^8.11.0",
    "ejs": "^3.1.9",
    "body-parser": "^1.20.2",
    "cors": "^2.8.5",
    "dotenv": "^16.3.1",
    "bcryptjs": "^2.4.3",
    "jsonwebtoken": "^9.0.2"
  }
}

2. .env.example

DATABASE_URL=your_database_url_here
PORT=3000
NODE_ENV=production

3. server.js (see previous message for full code)

4. public/index.html (see previous message for full code)

5. public/style.css (see previous message for full code)

6. public/script.js (see previous message for full code)

7. views/admin.ejs (see previous message for full code)

8. .gitignore

node_modules/
.env
.DS_Store
*.log

Upload to GitHub

git add .
git commit -m "Initial EpiPulse appointment booking system"
git push origin main

Step 2: Set Up Railway

Create Railway Account

  1. Go to Railway
    • Visit railway.app
    • Click “Start a New Project”
    • Choose “Deploy from GitHub”
  2. Connect GitHub
    • Click “Connect GitHub”
    • Authorize Railway to access your GitHub
    • Select your epipulse-appointments repository
  3. Create Database
    • Railway will ask to add a service
    • Select “PostgreSQL”
    • It creates automatically
    • Takes 1-2 minutes
  4. Deploy Application
    • Railway reads package.json
    • Creates Node.js environment
    • Automatic deployment begins
    • Watch the logs

Configure Environment Variables

Once deployed:

  1. Go to Project Settings

    • In Railway dashboard
    • Click your project
    • Go to “Variables”

  2. Add Variables (Railway auto-provides DATABASE_URL)

    PORT: 3000
NODE_ENV: production
DATABASE_URL: (automatically set)

  3. Save and Deploy

    • Changes trigger automatic redeployment
    • Takes 2-3 minutes

Step 3: Initialize Database

Create Database Tables

  1. Access Railway Database
    • In Railway, go to PostgreSQL service
    • Click “Connect”
    • Note connection details
  2. Run SQL Commands
    • Use pgAdmin or Railway’s built-in SQL editor
    • Run the init.sql file content:
-- Create services table
CREATE TABLE services (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  description TEXT,
  duration_minutes INTEGER DEFAULT 30,
  fee DECIMAL(10,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create appointments table
CREATE TABLE appointments (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  phone VARCHAR(20) NOT NULL,
  email VARCHAR(100) NOT NULL,
  dob DATE,
  gender VARCHAR(20),
  service_id INTEGER REFERENCES services(id),
  preferred_date DATE NOT NULL,
  time_slot VARCHAR(20) NOT NULL,
  health_concern TEXT,
  previous_consultation BOOLEAN DEFAULT FALSE,
  emergency BOOLEAN DEFAULT FALSE,
  status VARCHAR(20) DEFAULT 'pending',
  notes TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert services
INSERT INTO services (name, description, duration_minutes, fee) VALUES
('General OPD', 'Primary healthcare consultation', 30, 200.00),
('Deaddiction Consultation', 'Addiction assessment and counseling', 45, 300.00),
('NCD Care', 'Non-communicable disease management', 30, 250.00),
('Pediatric Care', 'Child healthcare services', 30, 250.00);

Step 4: Customize & Deploy

Update Appointment Code

  1. Edit server.js
    • Update email settings if needed
    • Customize responses
    • Add your organization name
  2. Update public/index.html
    • Change hospital/NGO name
    • Update contact information
    • Customize colors/branding
  3. Update views/admin.ejs
    • Admin dashboard customization
    • Add your logo
    • Customize form fields

Push Changes

git add .
git commit -m "Customize for EpiPulse"
git push origin main

Railway automatically deploys changes!

Step 5: Connect to Your Website

Embed Booking Form

Add to your services.qmd or dedicated booking page:

<iframe src="https://your-railway-app.railway.app" 
        width="100%" 
        height="800" 
        frameborder="0">
</iframe>

Replace your-railway-app with your actual Railway app URL (found in Railway dashboard).

Custom Domain (Optional)

  1. Add Custom Domain
    • In Railway dashboard
    • Go to “Settings”
    • Add your domain
    • Follow DNS instructions
  2. Example
    • Instead of: epipulse-123456.railway.app
    • Use: appointments.epipulse.org

Step 6: Test & Monitor

Test Booking System

  1. Book Test Appointment
    • Fill form with test data
    • Verify it appears in database
    • Check admin panel
  2. Check Database
    • Go to Railway PostgreSQL
    • Query: SELECT * FROM appointments;
    • Verify data saved correctly
  3. Test Notifications
    • Set up email notifications (optional)
    • Deploy email plugin
    • Test with real data

Monitor Deployments

  • Railway dashboard shows:
    • Application logs
    • Database usage
    • Deployment history
    • Performance metrics

Step 7: User Management

Patient Management

View Appointments

Admin Panel: /admin
Lists all bookings
Status: Pending, Confirmed, Completed

Update Status - Pending → Confirmed (when scheduling doctor) - Confirmed → Completed (after consultation) - Any → Cancelled (if patient cancels)

Admin Login (Optional)

To add admin authentication:

  1. Update server.js
// Add login route
app.post('/admin/login', (req, res) => {
  // Verify credentials
  // Start session
  // Redirect to admin panel
});
  1. Update views/admin.ejs
<!-- Add login form -->
<form method="POST" action="/admin/login">
  <input type="email" name="email" required>
  <input type="password" name="password" required>
  <button type="submit">Login</button>
</form>

Troubleshooting Railway

App Not Deploying

Problem: Railway shows deployment errors

Solution: - Check logs in Railway dashboard - Ensure package.json is correct - Verify GitHub repo is public - Check Node.js version compatibility

Database Connection Error

Problem: “Cannot connect to database”

Solution: - Verify DATABASE_URL in variables - Check PostgreSQL service is running - Ensure tables are created - Restart application from Railway

Form Not Submitting

Problem: Booking form not working

Solution: - Check browser console for errors - Verify server.js is running - Test database connection - Check CORS settings

Application Crashes

Problem: App keeps restarting

Solution: - Check error logs - Verify environment variables set - Ensure port 3000 is available - Review server.js for syntax errors

Maintenance & Updates

Regular Updates

Monthly: - Check Railway logs for errors - Backup database - Review bookings

Quarterly: - Update dependencies (npm update) - Review and optimize code - Check application performance

Backup Database

# Export data
pg_dump -U username dbname > backup.sql

# Import data
psql -U username dbname < backup.sql

Cost Analysis

Railway Free Tier

Monthly credits: $5
Daily spending: ~$0.15-0.30

Includes:
- Node.js application hosting
- PostgreSQL database (5GB)
- 100GB bandwidth (per month)
- SSL certificate
- Automatic backups

For EpiPulse:
- ~50-100 appointments/month
- 1GB database space used
- Cost: **COMPLETELY FREE**

Upgrade When Needed

If you exceed free tier: - Pay-as-you-go pricing - Transparent billing - No hidden charges - Easy to scale up/down

Simpler Alternative: Formspree (No Coding Required)

If Railway seems too complex, use Formspree:

Advantages: - ✅ No server setup required - ✅ No coding knowledge needed - ✅ 50 submissions/month free - ✅ Email notifications automatic - ✅ Quick 5-minute setup

Disadvantages: - Only basic form submissions - No patient database - Limited to 50 submissions/month - No advanced features

Setup Time: 5 minutes Vs Railway Setup Time: 45 minutes

Decision: Which to Choose?

Choose Railroad if:

  • You want your own appointment database
  • You need advanced features (patient history, automated confirmations)
  • You want complete control and independence
  • You plan to scale significantly
  • You want professional presentation

Choose Formspree if:

  • You want quick setup (5 minutes vs 45 minutes)
  • You don’t need patient database
  • You’re comfortable managing data in spreadsheets
  • You want zero technical complexity
  • You just starting out

Next Steps

  1. Create GitHub Account → github.com
  2. Create Railway Account → railway.app
  3. Follow Step 1-3 Above → Complete in 30 minutes
  4. Test System → Book test appointment
  5. Go Live → Add to your website

Need Help? - Email: tech-support@epipulse.org - Consult: Railway Documentation - GitHub: Railway GitHub

Your appointment system, your way, for free!