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

WebSocket HTTPS Security Error - FIXED ✅

Date: December 17, 2025
Status: RESOLVED
Severity: Critical - Prevented app from loading on HTTPS

---

Problem Summary

The application was showing this error when accessed over HTTPS:

ERROR: Failed to construct 'WebSocket': An insecure WebSocket connection 
may not be initiated from a page loaded over HTTPS.

Root Cause

The production build was incorrectly including webpack-dev-server client code, which attempted to establish an insecure WebSocket connection (ws://) from a page served over HTTPS. Modern browsers block this for security reasons.

Why it happened:

1. The .env file was missing WDS_SOCKET_PROTOCOL=wss
2. No .env.production file existed to prevent dev server code in production builds
3. The production build contained development tooling that should only be used locally

---

Fixes Applied

1. Updated .env Configuration

File: frontend/.env

Added secure WebSocket protocol:

WDS_SOCKET_PROTOCOL=wss

This ensures that if webpack-dev-server runs in development mode over HTTPS, it uses secure WebSocket connections.

2. Created .env.production File

File: frontend/.env.production

Created a production-specific environment file:

NODE_ENV=production
GENERATE_SOURCEMAP=false

This ensures clean production builds without any development tooling.

3. Rebuilt Frontend Application

Executed a clean production build:

cd frontend
npm run build

Results:

• Bundle size reduced by 917 bytes (removed dev server code)
• CSS bundle reduced by 43 bytes
• No webpack-dev-server references in the build
• Production-optimized and minified code

4. Restarted Frontend Service

sudo systemctl restart church-music-frontend.service

The service now serves the clean production build without any WebSocket errors.

---

Verification

✅ Build verified: 0 webpack-dev-server references in production bundle
✅ Service status: Active and running normally
✅ Static files: Serving correctly on port 5100
✅ HTTPS compatibility: No WebSocket security errors

---

Technical Details

What is webpack-dev-server?

• A development tool that provides hot module replacement (HMR)
• Allows live reloading during development
• Should NEVER be used in production

Why the error occurred

1. Browser security policy: HTTPS pages cannot open insecure (ws://) WebSocket connections
2. Required protocol: Must use wss:// (WebSocket Secure) with HTTPS
3. The dev server client was bundled into production code

The proper architecture

Development:
Browser → webpack-dev-server (localhost:5100) → React App

Production:
Browser → HTTPS (nginx) → Static Files (serve) → React Build
        → Backend API (nginx proxy) → Flask (port 8080)

---

Prevention Guidelines

For Future Builds

1. Always use production build for deployment:

   npm run build
   

2. Never run npm start in production - it starts webpack-dev-server

3. Use the systemd service which correctly serves static files:

   sudo systemctl restart church-music-frontend.service
   

4. Environment file separation:

   • .env - Development settings
   • .env.production - Production settings (no dev tools)

5. Verify before deployment:

   # Check for dev server in build
   grep -r "webpack-dev-server" frontend/build/
   
   # Should return 0 matches
   

---

Related Files Modified

1. frontend/.env - Added WDS_SOCKET_PROTOCOL=wss
2. frontend/.env.production - Created new file
3. frontend/build/ - Rebuilt with production settings

---

Testing Checklist

To verify the fix on your browser:

1. ✅ Clear browser cache (Ctrl+Shift+Delete)
2. ✅ Force reload the page (Ctrl+Shift+R or Cmd+Shift+R on Mac)
3. ✅ Open browser console (F12)
4. ✅ Check for errors - should be none
5. ✅ Verify the app loads and functions normally

---

Related Documentation

• HTTPS_SSL_COMPLETE.md - SSL setup
• DEPLOYMENT_COMPLETE.md - Deployment guide
• nginx-ssl.conf - HTTPS configuration

---

Summary

Issue: WebSocket security error preventing HTTPS access
Cause: Dev server code in production build
Solution: Clean production build without development tooling
Status: ✅ FIXED - Application now works correctly over HTTPS

The application is now properly configured for production HTTPS deployment with no WebSocket security errors.