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

# 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.