Church-Music/legacy-site/documentation/md-files/CONFIGURATION_GUIDE.md

Configuration Guide - Port Setup Explained

Understanding the Two Ports

Your worship system has two separate services running on two different ports:

Service	Port	What It Does
Backend (Flask API)	5000	Handles data storage, database queries, API endpoints
Frontend (React UI)	3000	Displays the user interface (web pages)

How It Works

1. You access the app by opening the frontend at port 3000 in your browser
2. The frontend JavaScript then makes API calls to the backend at port 5000
3. You must configure the Settings page to tell the frontend where the backend API is located

Desktop/Local Machine Setup

Step 1: Start Both Services

Backend (API Server):

cd "E:\Documents\Website Projects\Church_SongLyric\backend"
python app.py

✅ Backend running on http://localhost:5000

Frontend (React UI):

cd "E:\Documents\Website Projects\Church_SongLyric\frontend"
npm start

✅ Frontend running on http://localhost:3000

Step 2: Configure Settings

1. Open http://localhost:3000 in your browser
2. Click Settings (⚙️)
3. Toggle OFF "Local Mode" (disable the switch)
4. Enter these values:
   • Protocol: http
   • Hostname: localhost
   • Port: 5000 ← This is the BACKEND port
5. Click 💾 Save DNS Settings
6. Page will reload

✅ Your desktop is now configured!

Mobile/Tablet Setup

Step 1: Find Your Desktop's LAN IP

The backend script shows your LAN IP when it starts. Common examples:

• 10.5.0.2
• 192.168.1.50
• 192.168.0.100

Step 2: Access Frontend on Mobile

Open your mobile browser and go to:

http://YOUR_LAN_IP:3000

Examples:

• http://10.5.0.2:3000
• http://192.168.1.50:3000

Step 3: Configure Settings on Mobile

1. Click Settings (⚙️)
2. Toggle OFF "Local Mode" (disable the switch)
3. Enter these values:
   • Protocol: http
   • Hostname: 10.5.0.2 ← Your desktop's LAN IP
   • Port: 5000 ← This is the BACKEND port (NOT 3000)
4. Click 💾 Save DNS Settings
5. Page will reload with synced data

✅ Your mobile is now configured!

Common Mistakes

❌ Wrong: Setting mobile port to 3000

• Port 3000 is just the React UI - it has no API backend

✅ Correct: Setting mobile port to 5000

• Port 5000 is where the backend API lives

❌ Wrong: Accessing http://10.5.0.2:5000 on mobile

• This shows raw API responses, not the user interface

✅ Correct: Accessing http://10.5.0.2:3000 on mobile

• This loads the React UI, which then calls the API at port 5000

Troubleshooting

"Showing Offline" on Desktop

Cause: Settings are in "Local Mode" or not configured correctly

Fix:

1. Go to Settings
2. Toggle OFF "Local Mode"
3. Set hostname=localhost, port=5000
4. Click Save

"Can't Sync" on Mobile

Cause: Wrong port or hostname in Settings

Fix:

1. Go to Settings on mobile
2. Toggle OFF "Local Mode"
3. Set hostname to your desktop's LAN IP (e.g., 10.5.0.2)
4. Set port to 5000 (NOT 3000)
5. Click Save

How to Check Backend Health

Desktop:

http://localhost:5000/api/health

Mobile (replace with your LAN IP):

http://10.5.0.2:5000/api/health

Should show: {"status":"ok"}

Quick Reference Card

Where	Access URL	Settings Hostname	Settings Port
Desktop	http://localhost:3000	localhost	5000
Mobile	http://10.5.0.2:3000	10.5.0.2	5000

Remember: Access on 3000, Configure to 5000