Initial commit - Church Music Database

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

@@ -0,0 +1,156 @@
+# 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):**
+
+```powershell
+cd "E:\Documents\Website Projects\Church_SongLyric\backend"
+python app.py
+```
+
+✅ Backend running on `http://localhost:5000`
+
+**Frontend (React UI):**
+
+```powershell
+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**