Initial commit - Church Music Database
This commit is contained in:
368
legacy-site/documentation/md-files/SYNC_SETUP_GUIDE.md
Normal file
368
legacy-site/documentation/md-files/SYNC_SETUP_GUIDE.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Church SongLyric - Multi-Device Sync Setup Guide
|
||||
|
||||
## Backend Server Setup
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```powershell
|
||||
cd "E:\Documents\Website Projects\Church_SongLyric\backend"
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Start the Backend Server
|
||||
|
||||
**Development (auto-restart on changes):**
|
||||
|
||||
```powershell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**Production:**
|
||||
|
||||
```powershell
|
||||
npm start
|
||||
```
|
||||
|
||||
The server will start on `http://localhost:5000` by default.
|
||||
|
||||
---
|
||||
|
||||
## Frontend Configuration
|
||||
|
||||
### Option 1: Use Settings UI (Recommended)
|
||||
|
||||
1. Open the app in your browser
|
||||
2. Navigate to **Settings** page
|
||||
3. Configure **Online/DNS Settings**:
|
||||
- **Protocol**: `http` or `https`
|
||||
- **Hostname**: `localhost` (local) or your No-IP hostname (remote)
|
||||
- **Port**: `5000`
|
||||
- **Access Mode**: Toggle between Local Storage (offline) and Online (synced)
|
||||
4. Click **Save Settings**
|
||||
5. Refresh the page to connect
|
||||
|
||||
### Option 2: Manual Configuration
|
||||
|
||||
Edit `frontend/src/api.js` and modify:
|
||||
|
||||
```javascript
|
||||
useLocalStorage: false // Enable backend sync
|
||||
hostname: "localhost" // Or your No-IP hostname
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Local Network Access (Multiple Devices on Same Wi-Fi)
|
||||
|
||||
### 1. Find Your Computer's Local IP
|
||||
|
||||
```powershell
|
||||
ipconfig
|
||||
```
|
||||
|
||||
Look for **IPv4 Address** under your active network adapter (e.g., `192.168.1.50`)
|
||||
|
||||
### 2. Configure Frontend Settings
|
||||
|
||||
- **Hostname**: Use your local IP (e.g., `192.168.1.50`)
|
||||
- **Port**: `5000`
|
||||
- **Access Mode**: Online
|
||||
|
||||
### 3. Access from Other Devices
|
||||
|
||||
Open browser on tablet/phone/laptop and navigate to:
|
||||
|
||||
```text
|
||||
http://192.168.1.50:3000
|
||||
```
|
||||
|
||||
All devices will now share the same database via the backend server.
|
||||
|
||||
---
|
||||
|
||||
## External Access Setup (No-IP Dynamic DNS)
|
||||
|
||||
### Step 1: Create No-IP Account
|
||||
|
||||
1. Go to <https://www.noip.com/>
|
||||
2. Sign up for free account (supports 3 hostnames)
|
||||
3. Verify email
|
||||
|
||||
### Step 2: Create Hostname
|
||||
|
||||
1. Login to No-IP dashboard
|
||||
2. Navigate to **Dynamic DNS** → **No-IP Hostnames**
|
||||
3. Click **Create Hostname**
|
||||
4. Choose a hostname: `churchlyrics.ddns.net` (or your preference)
|
||||
5. Set **Record Type**: A (IPv4 Address)
|
||||
6. Leave IP auto-detected (your current public IP)
|
||||
7. Click **Create Hostname**
|
||||
|
||||
### Step 3: Assign Static Local IP (Windows)
|
||||
|
||||
1. Open **Settings** → **Network & Internet** → **Ethernet** (or Wi-Fi)
|
||||
2. Click **Properties**
|
||||
3. Click **Edit** under IP assignment
|
||||
4. Select **Manual**
|
||||
5. Enable **IPv4**
|
||||
6. Set:
|
||||
- **IP Address**: `192.168.1.50` (adjust to your subnet)
|
||||
- **Subnet Mask**: `255.255.255.0`
|
||||
- **Gateway**: Your router IP (usually `192.168.1.1`)
|
||||
- **DNS**: `8.8.8.8` (Google DNS)
|
||||
7. Save
|
||||
|
||||
### Step 4: Configure Router Port Forwarding
|
||||
|
||||
1. Login to router admin panel (usually `http://192.168.1.1`)
|
||||
2. Navigate to **Port Forwarding** or **Virtual Server**
|
||||
3. Add new rule:
|
||||
- **Service Name**: ChurchSongLyric API
|
||||
- **External Port**: `5000`
|
||||
- **Internal IP**: `192.168.1.50` (your static IP)
|
||||
- **Internal Port**: `5000`
|
||||
- **Protocol**: TCP
|
||||
4. Add another rule for frontend (if exposing React dev server):
|
||||
- **External Port**: `3000`
|
||||
- **Internal IP**: `192.168.1.50`
|
||||
- **Internal Port**: `3000`
|
||||
- **Protocol**: TCP
|
||||
5. Save and reboot router if required
|
||||
|
||||
### Step 5: Install No-IP Dynamic Update Client (DUC)
|
||||
|
||||
1. Download from <https://www.noip.com/download>
|
||||
2. Install and login with your No-IP credentials
|
||||
3. Select the hostname you created
|
||||
4. Click **Save**
|
||||
5. Enable **Start on Windows Startup** in settings
|
||||
6. The client will auto-update your public IP when it changes
|
||||
|
||||
### Step 6: Configure Windows Firewall
|
||||
|
||||
**Allow Backend Port:**
|
||||
|
||||
```powershell
|
||||
New-NetFirewallRule -DisplayName "ChurchSongLyric API" -Direction Inbound -Protocol TCP -LocalPort 5000 -Action Allow
|
||||
```
|
||||
|
||||
**Allow Frontend Port (if needed):**
|
||||
|
||||
```powershell
|
||||
New-NetFirewallRule -DisplayName "ChurchSongLyric Frontend" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
1. Open **Windows Security** → **Firewall & Network Protection**
|
||||
2. Click **Advanced Settings**
|
||||
3. Select **Inbound Rules** → **New Rule**
|
||||
4. Choose **Port** → **TCP** → Enter `5000`
|
||||
5. Select **Allow the connection**
|
||||
6. Name it: `ChurchSongLyric API`
|
||||
7. Repeat for port `3000` if needed
|
||||
|
||||
### Step 7: Test External Access
|
||||
|
||||
From a mobile device on cellular (not Wi-Fi):
|
||||
|
||||
```text
|
||||
http://churchlyrics.ddns.net:5000/api/songs
|
||||
```
|
||||
|
||||
Should return JSON (empty array initially).
|
||||
|
||||
### Step 8: Update Frontend Settings
|
||||
|
||||
In Settings UI:
|
||||
|
||||
- **Protocol**: `http`
|
||||
- **Hostname**: `churchlyrics.ddns.net`
|
||||
- **Port**: `5000`
|
||||
- **Access Mode**: Online
|
||||
|
||||
Save and refresh.
|
||||
|
||||
---
|
||||
|
||||
## Security Hardening (Recommended)
|
||||
|
||||
### 1. Add API Key Authentication
|
||||
|
||||
Edit `backend/server.js` and add middleware:
|
||||
|
||||
```javascript
|
||||
const API_KEY = process.env.API_KEY || 'your-secret-key-here';
|
||||
|
||||
app.use('/api', (req, res, next) => {
|
||||
const key = req.headers['x-api-key'];
|
||||
if (key !== API_KEY) {
|
||||
return res.status(401).json({ error: 'Unauthorized' });
|
||||
}
|
||||
next();
|
||||
});
|
||||
```
|
||||
|
||||
Update frontend requests to include header:
|
||||
|
||||
```javascript
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": "your-secret-key-here"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Enable HTTPS (Production)
|
||||
|
||||
Install Caddy (reverse proxy with auto HTTPS):
|
||||
|
||||
```powershell
|
||||
choco install caddy
|
||||
```
|
||||
|
||||
Create `Caddyfile`:
|
||||
|
||||
```text
|
||||
churchlyrics.ddns.net {
|
||||
reverse_proxy localhost:5000
|
||||
}
|
||||
```
|
||||
|
||||
Update port forwarding to 443 (HTTPS) instead of 5000.
|
||||
|
||||
### 3. Regular Backups
|
||||
|
||||
Schedule automatic backups of `backend/data.json`:
|
||||
|
||||
```powershell
|
||||
# Add to Task Scheduler
|
||||
Copy-Item "E:\Documents\Website Projects\Church_SongLyric\backend\data.json" `
|
||||
-Destination "E:\Backups\church_data_$(Get-Date -Format yyyyMMdd_HHmmss).json"
|
||||
```
|
||||
|
||||
### 4. Restrict WebSocket Origins
|
||||
|
||||
In `server.js`:
|
||||
|
||||
```javascript
|
||||
wss.on('connection', (ws, req) => {
|
||||
const origin = req.headers.origin;
|
||||
const allowed = ['http://localhost:3000', 'http://churchlyrics.ddns.net:3000'];
|
||||
if (!allowed.includes(origin)) {
|
||||
ws.close();
|
||||
return;
|
||||
}
|
||||
// ... rest of connection logic
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real-Time Sync Features
|
||||
|
||||
### How It Works
|
||||
|
||||
- Backend broadcasts changes via WebSocket when any device creates/updates/deletes data
|
||||
- All connected clients receive notifications and automatically refresh their UI
|
||||
- No manual page reload needed
|
||||
|
||||
### Supported Events
|
||||
|
||||
- `songsChanged`: When songs are added/edited/deleted
|
||||
- `plansChanged`: When worship plans are modified
|
||||
- `profilesChanged`: When profiles are updated
|
||||
- `profileSongsChanged`: When profile song associations change
|
||||
|
||||
### Testing Sync
|
||||
|
||||
1. Open app on two devices (or two browser tabs)
|
||||
2. Create a new song on Device A
|
||||
3. Device B will automatically show the new song without refresh
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Backend won't start
|
||||
|
||||
```powershell
|
||||
# Check if port is already in use
|
||||
Get-NetTCPConnection -LocalPort 5000
|
||||
# Kill the process if needed
|
||||
Stop-Process -Id <PID>
|
||||
```
|
||||
|
||||
### Can't connect from other devices
|
||||
|
||||
1. Verify firewall rules are active
|
||||
2. Check router port forwarding is saved
|
||||
3. Ensure static IP is configured correctly
|
||||
4. Test local connection first (`http://localhost:5000/api/songs`)
|
||||
|
||||
### WebSocket disconnects frequently
|
||||
|
||||
- Check network stability
|
||||
- Ensure No-IP DUC is running and updating
|
||||
- Verify router isn't closing idle connections (adjust timeout settings)
|
||||
|
||||
### Data not syncing
|
||||
|
||||
1. Open browser console (F12)
|
||||
2. Check for WebSocket connection logs:
|
||||
- `✅ WebSocket connected` = working
|
||||
- `❌ WebSocket error` = connection failed
|
||||
3. Verify `useLocalStorage` is set to `false` in Settings
|
||||
4. Test API directly: `http://your-host:5000/api/songs`
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Enable Compression
|
||||
|
||||
Add to `server.js`:
|
||||
|
||||
```javascript
|
||||
import compression from 'compression';
|
||||
app.use(compression());
|
||||
```
|
||||
|
||||
### Database Migration (Future)
|
||||
|
||||
For larger deployments, consider migrating from file-based storage to:
|
||||
|
||||
- **SQLite**: Lightweight, file-based SQL database
|
||||
- **MongoDB**: NoSQL document store
|
||||
- **PostgreSQL**: Full-featured relational database
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **No-IP Documentation**: <https://www.noip.com/support>
|
||||
- **Express.js Guide**: <https://expressjs.com/>
|
||||
- **WebSocket API**: <https://developer.mozilla.org/en-US/docs/Web/API/WebSocket>
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
1. Check backend console for error logs
|
||||
2. Check browser console (F12) for frontend errors
|
||||
3. Verify all ports are open and forwarded correctly
|
||||
4. Test each layer: localhost → LAN → external
|
||||
|
||||
**Quick Test Commands:**
|
||||
|
||||
```powershell
|
||||
# Test local backend
|
||||
curl http://localhost:5000/api/songs
|
||||
|
||||
# Test from LAN
|
||||
curl http://192.168.1.50:5000/api/songs
|
||||
|
||||
# Test external (from mobile cellular)
|
||||
curl http://churchlyrics.ddns.net:5000/api/songs
|
||||
```
|
||||
Reference in New Issue
Block a user