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):**

```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**