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
  • 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

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