Initial commit - Church Music Database

2026-01-27 18:04:50 -06:00
commit d367261867
336 changed files with 103545 additions and 0 deletions
--- a/legacy-site/documentation/md-files/EXTERNAL_ACCESS_CHECKLIST.md
+++ b/legacy-site/documentation/md-files/EXTERNAL_ACCESS_CHECKLIST.md
@@ -0,0 +1,153 @@
+# External Access Checklist
+
+Use this checklist to troubleshoot remote access issues when accessing your Church SongLyric backend from outside your local network.
+
+## Prerequisites
+
+- [ ] **Backend Server Running**
+  - Node.js backend started: `node backend/server.js`
+  - Server listening on `0.0.0.0:5000` (not `127.0.0.1`)
+  - Verify locally: `curl http://localhost:5000/api/health`
+
+## DNS Configuration
+
+- [ ] **No-IP Account Setup**
+  - Free account created at [NoIP.com](https://www.noip.com)
+  - Hostname registered (e.g., `mychurch.noip.org`)
+  - No-IP Dynamic Update Client (DUC) installed on server PC
+  - DUC running and hostname status shows "Up to date"
+
+- [ ] **DNS Resolution Test**
+  - Open PowerShell and run: `nslookup yourhost.noip.org`
+  - Should return your public IP address
+  - Wait 5-10 minutes after DUC update if recently changed
+
+## Firewall Configuration
+
+- [ ] **Windows Firewall Inbound Rule**
+  - Open Windows Defender Firewall → Advanced Settings → Inbound Rules
+  - Create new rule: TCP port `5000`, allow connection
+  - Rule applies to: Domain, Private, and Public profiles
+  - Test: `netstat -ano | findstr :5000` should show `0.0.0.0:5000` listening
+
+## Router Configuration
+
+- [ ] **Port Forwarding**
+  - Access router admin panel (usually `192.168.1.1` or `192.168.0.1`)
+  - Navigate to Port Forwarding / Virtual Server / NAT
+  - Create rule:
+    - External Port: `5000`
+    - Internal IP: Your server's local IP (e.g., `192.168.10.178`)
+    - Internal Port: `5000`
+    - Protocol: TCP
+  - Save and reboot router if required
+
+- [ ] **Static IP Assignment (Recommended)**
+  - Assign static local IP to server PC via router DHCP reservation
+  - Prevents IP changes after reboot breaking port forward rule
+
+- [ ] **Router NAT Loopback**
+  - Note: Some routers don't support accessing external URL from inside network
+  - If external URL fails from inside network but works from mobile data, this is expected
+
+## ISP Considerations
+
+- [ ] **CGNAT Check**
+  - Compare public IP (Google "what is my IP") with router WAN IP
+  - If different, ISP may be using CGNAT (blocks inbound connections)
+  - Solution: Use Tailscale VPN or cloud tunnel (Cloudflare, ngrok)
+
+- [ ] **Port 5000 Not Blocked**
+  - Some ISPs block common server ports
+  - Test alternative port (e.g., `8080`, `3000`) if issues persist
+
+## Testing
+
+- [ ] **Local Network Test**
+  - From same Wi-Fi: `curl http://192.168.10.178:5000/api/health`
+  - Should return `{"status":"ok",...}`
+
+- [ ] **External Test (Critical)**
+  - **Disconnect from Wi-Fi, use mobile data**
+  - Run: `curl http://yourhost.noip.org:5000/api/health`
+  - Or visit URL in mobile browser
+  - Success = external access working
+
+- [ ] **Health Check Script**
+  - Run from any PC: `.\backend\health-check.ps1 http://yourhost.noip.org:5000`
+  - All three tests should pass
+
+## Diagnostics Panel (In-App)
+
+- [ ] **Run Built-In Diagnostics**
+  - Open Settings → Connectivity Diagnostics
+  - Click "Run Diagnostics"
+  - All tests should show ✅:
+    1. DNS Resolution
+    2. Localhost Connectivity
+    3. Backend Connectivity
+    4. Local Network (LAN) Test
+
+## Common Failures & Solutions
+
+| Symptom | Likely Cause | Solution |
+|---------|-------------|----------|
+| DNS test fails | No-IP DUC not running or hostname not updated | Start DUC, wait 5 min, retry |
+| Localhost works, external fails | Port not forwarded or firewall blocking | Check router port forward + firewall rule |
+| Works on mobile data, fails on Wi-Fi | Router NAT loopback unsupported | Expected behavior; use localhost URL when on same network |
+| All tests timeout | Backend not running or listening on wrong interface | Restart backend, ensure binding to `0.0.0.0` |
+| Connection refused | ISP CGNAT or port blocked | Try alternative port or use Tailscale/tunnel |
+
+## Alternative Solutions
+
+If direct port forwarding fails:
+
+1. **Tailscale VPN** (Recommended)
+   - Install on server and client devices
+   - Secure peer-to-peer connection, no port forwarding needed
+   - See `TUNNEL_SETUP_GUIDE.md` for setup
+
+2. **LocalTunnel**
+   - Quick public HTTPS URL
+   - Run: `npx localtunnel --port 5000 --subdomain mychurch`
+   - See `TUNNEL_SETUP_GUIDE.md` for setup
+
+3. **Cloudflare Tunnel / ngrok**
+   - Enterprise-grade tunneling
+   - Free tier available
+
+## Support Commands
+
+```powershell
+# Check backend process
+Get-Process -Name node | Where-Object {$_.Path -like "*Church_SongLyric*"}
+
+# Verify port listening
+netstat -ano | findstr :5000
+
+# Test localhost
+curl http://localhost:5000/api/health
+
+# Test LAN IP
+curl http://192.168.10.178:5000/api/health
+
+# DNS lookup
+nslookup yourhost.noip.org
+
+# Firewall rules
+netsh advfirewall firewall show rule name=all | Select-String "5000"
+
+# Get local IP
+ipconfig | Select-String "IPv4"
+```
+
+## Final Verification
+
+Once all checkboxes complete:
+
+1. From mobile data: Visit `http://yourhost.noip.org:5000` in browser
+2. Should see: `{"message":"House of Prayer Song Lyrics API (Node)","port":5000}`
+3. Update frontend Settings → Online Mode with your No-IP hostname
+4. Save settings and test song sync across devices
+
+✅ **Success!** Your Church SongLyric system is now accessible remotely.