plot-pulse

Railway Deployment Guide - PlotPulse Backend

Complete guide for deploying PlotPulse backend to Railway with PostGIS database.

Prerequisites
Initial Setup
PostGIS Database Setup
Backend Configuration
Networking & Port Configuration
Testing & Verification
Troubleshooting

Prerequisites

Railway account: https://railway.app (Sign up with GitHub)
GitHub repository with your backend code
Railway CLI (optional, for database access): npm i -g @railway/cli

Initial Setup

1. Create Railway Project

Go to https://railway.app
Click “New Project” → “Deploy from GitHub repo”
Select your repository (plot-pulse)
Railway will create a service automatically

2. Configure Service Root Directory

⚠️ CRITICAL: Railway needs to know where your Dockerfile is.

Go to your service → Settings tab
Find “Root Directory” setting
Set it to: backend
This tells Railway to look for backend/Dockerfile

PostGIS Database Setup

Step 1: Create PostGIS Service

Important: Use PostGIS, NOT regular PostgreSQL!

In Railway project, click ”+ New” → “Database”
Select “Add PostGIS” (not PostgreSQL)
Wait for deployment (green checkmark = “Deployment Online”)

Step 2: Enable PostGIS Extensions

Option A: Using Railway CLI (Recommended)

# Connect to PostGIS
railway connect postgis

# In psql prompt, run:
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS postgis_topology;

# Verify:
\dx

# Exit:
\q

Option B: Using Railway Dashboard

Go to PostGIS service → “Database” tab
Use the SQL editor (if available)
Run the same SQL commands

Step 3: Get Database Connection Variables

Go to PostGIS service → “Variables” tab
Note these values (you’ll need them):
- PGHOST = postgis.railway.internal (for internal connection)
- PGPORT = 5432
- PGDATABASE = railway (default database name)
- PGUSER = postgres
- POSTGRES_PASSWORD = (copy this value - this is the actual password)

Backend Configuration

Step 1: Connect Database to Backend Service

Option A: Add Reference (If Available)

Go to plot-pulse service → “Variables” tab
Click “Add Reference” button
Select your PostGIS service
Railway will automatically add database variables

Option B: Manual Setup (If Reference Not Available)

Go to plot-pulse service → “Variables” tab
Add these variables manually (copy from PostGIS Variables tab):

Variable	Value
`PGHOST`	`postgis.railway.internal`
`PGPORT`	`5432`
`PGDATABASE`	`railway`
`PGUSER`	`postgres`
`PGPASSWORD`	(copy from PostGIS `POSTGRES_PASSWORD`)

Step 2: Set Required Application Variables

In plot-pulse service → “Variables” tab, add:

Variable	Value	Notes
`SPRING_PROFILES_ACTIVE`	`prod,railway`	REQUIRED - Use `prod,railway` to enable Railway-specific overrides
`JWT_SECRET`	(generate secure secret)	REQUIRED - See below
`FRONTEND_URL`	`https://plotpulse.syrez.co.in`	Optional - for CORS

Note: Using prod,railway profile enables Railway-specific configurations:

Server binds to 0.0.0.0 (required for Railway networking)
Uses PORT environment variable (Railway’s convention)
Database defaults to railway (Railway’s default database name)
SSL mode set to disable for internal connections (Railway’s internal network)

Generate JWT_SECRET:

# PowerShell
[Convert]::ToBase64String((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Or use this pre-generated one (for testing only - generate new for production):

5Bm9beXKU/sYEBBVJiho28/hBb2BmRWnLYxHUa7KdAIY8y73tBBmJSnSLHPNsQt4Io1L2MM0qU7qmgELBr9eoQ==

Step 3: Verify All Variables

Your plot-pulse service should have:

✅ SPRING_PROFILES_ACTIVE=prod,railway (use prod,railway to enable Railway-specific overrides) ✅ JWT_SECRET (secure value) ✅ PGHOST=postgis.railway.internal ✅ PGPORT=5432 ✅ PGDATABASE=railway ✅ PGUSER=postgres ✅ PGPASSWORD (from PostGIS)

Networking & Port Configuration

⚠️ CRITICAL: Port Configuration

This is the most common issue causing 502 errors!

Go to plot-pulse service → Settings → Networking
Check the “Custom port” setting:
- Option 1 (Recommended): Select “Default” or “Auto” from dropdown
  - This lets Railway auto-detect the port from the PORT environment variable
- Option 2: Manually set to match what the backend is using
  - Check deployment logs for: 🚀 Server started successfully! Listening on: 0.0.0.0:XXXX
  - Set the port to match (usually 8080)
Important: The backend uses Railway’s PORT environment variable automatically
- Backend config: server.port: ${PORT:${SERVER_PORT:8091}}
- Railway sets PORT automatically - don’t override it manually

Get Your Public Domain

Go to plot-pulse service → Settings → Networking
Your public domain will be shown: plot-pulse-production.up.railway.app
Your API base URL: https://plot-pulse-production.up.railway.app/api/v1

Testing & Verification

1. Check Deployment Logs

Go to plot-pulse → Deployments → Latest deployment → View logs

Success indicators:

🚀 Server started successfully!
   Listening on: 0.0.0.0:8080
   Context path: /api/v1
Started ProjectApplication in XX seconds

Error indicators:

Connection to localhost:5432 refused → Database variables not set
Could not resolve placeholder 'JWT_SECRET' → JWT_SECRET not set
Unsupported Database: PostgreSQL 16.9 → Flyway PostgreSQL driver missing (should be fixed)

2. Test Health Endpoint

Open in browser:

https://plot-pulse-production.up.railway.app/api/v1/health
Should return: {"status":"SUCCESS","message":"Application is running",...}

3. Test from Frontend

Update frontend/.env.development:

VITE_API_BASE_URL=https://plot-pulse-production.up.railway.app/api/v1

Start frontend:
```
cd frontend
npm run dev
```
Test API calls - should work without CORS errors

Troubleshooting

Issue: “Application failed to respond” / 502 Bad Gateway

Cause: Port mismatch between Railway networking and backend

Solution:

Check deployment logs for actual port: 🚀 Server started successfully! Listening on: 0.0.0.0:XXXX
Go to Settings → Networking → “Custom port” dropdown
Option 1 (Recommended): Select “Default” or “Auto” to auto-detect from PORT env var
Option 2: Manually set port to match what backend is using (usually 8080)
Click “Update” and wait for redeploy

Important: Backend uses ${PORT} environment variable. Railway sets this automatically - don’t override it manually.

Issue: “Connection to localhost:5432 refused”

Cause: Database variables not set or wrong values

Solution:

Verify all PG* variables are set in plot-pulse service
Use postgis.railway.internal for PGHOST (internal connection)
Use POSTGRES_PASSWORD value from PostGIS service (not PGPASSWORD)

Issue: “Could not resolve placeholder ‘JWT_SECRET’”

Cause: JWT_SECRET environment variable not set

Solution:

Go to plot-pulse → Variables
Add JWT_SECRET with a secure value
Redeploy

Issue: “Schema-validation: missing table [table_name]”

Cause: Flyway migrations not running

Solution:

Verify spring.flyway.enabled=true in application-prod.yml

Check Flyway dependency in pom.xml:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>10.20.1</version>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
    <version>10.20.1</version>
</dependency>

Check migration files exist in backend/src/main/resources/db/migration/

Issue: CORS Errors from Frontend

Cause: CORS not configured or origin not allowed

Solution:

Verify http://localhost:5173 is in application-prod.yml CORS allowed-origins
Check backend logs for CORS configuration
Hard refresh browser (Ctrl+Shift+R)

Issue: “Unsupported Database: PostgreSQL 16.9”

Cause: Flyway version doesn’t support PostgreSQL 16

Solution:

Ensure both Flyway dependencies are in pom.xml:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>10.20.1</version>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
    <version>10.20.1</version>
</dependency>

Issue: “Script start.sh not found” or “Railpack could not determine how to build”

Cause: Railway can’t find build configuration

Solution:

Go to service → Settings → Root Directory
Set to: backend
Redeploy

Issue: Build fails with “/src: not found” or “/backend/src: not found”

Cause: Dockerfile paths incorrect for Railway build context

Solution:

Dockerfile should use: COPY backend/pom.xml ./pom.xml and COPY backend/src/ ./src/
This is already configured correctly in the current Dockerfile

Issue: Build fails with test errors

Cause: Maven tests failing during Docker build

Solution:

Tests are skipped during Docker build using -Dmaven.test.skip=true
If tests fail locally, run: cd backend && mvn test to fix them

Database Access

Method 1: Railway CLI (Easiest)

# Connect to PostGIS
railway connect postgis

# Now you're in psql - run SQL commands directly
SELECT * FROM users;
\q  # to exit

Method 2: Railway Dashboard

Go to PostGIS service → “Database” tab
Use SQL editor (if available)

Method 3: External Client

PostGIS service → Variables tab
Copy connection details:
- Host: shortline.proxy.rlwy.net (external) or postgis.railway.internal (internal)
- Port: 34889 (external) or 5432 (internal)
- Database: railway
- Username: postgres
- Password: (from POSTGRES_PASSWORD)
Connect with pgAdmin, DBeaver, or TablePlus

Quick Reference Checklist

Important Notes

Always use PostGIS template, not regular PostgreSQL
Use internal hostname (postgis.railway.internal) for faster connections
Port configuration is critical - mismatch causes 502 errors
Flyway migrations run automatically on startup (if enabled)
Database name is railway by default (Railway’s convention)
CORS is configured for localhost:5173 - add production domains when ready

Next Steps

After successful deployment:

Update frontend production environment variables
Configure custom domain (if needed)
Set up monitoring and alerts
Review security settings
Set up backups for PostGIS database

plot-pulse

Railway Deployment Guide - PlotPulse Backend

Table of Contents

Prerequisites

Initial Setup

1. Create Railway Project

2. Configure Service Root Directory

PostGIS Database Setup

Step 1: Create PostGIS Service

Step 2: Enable PostGIS Extensions

Step 3: Get Database Connection Variables

Backend Configuration

Step 1: Connect Database to Backend Service

Step 2: Set Required Application Variables

Step 3: Verify All Variables

Networking & Port Configuration

⚠️ CRITICAL: Port Configuration

Get Your Public Domain

Testing & Verification

1. Check Deployment Logs

2. Test Health Endpoint

3. Test from Frontend

Troubleshooting

Issue: “Application failed to respond” / 502 Bad Gateway

Issue: “Connection to localhost:5432 refused”

Issue: “Could not resolve placeholder ‘JWT_SECRET’”

Issue: “Schema-validation: missing table [table_name]”

Issue: CORS Errors from Frontend

Issue: “Unsupported Database: PostgreSQL 16.9”

Issue: “Script start.sh not found” or “Railpack could not determine how to build”

Issue: Build fails with “/src: not found” or “/backend/src: not found”

Issue: Build fails with test errors

Database Access

Method 1: Railway CLI (Easiest)

Method 2: Railway Dashboard

Method 3: External Client

Quick Reference Checklist

Important Notes

Next Steps