Add STATIC environment variable for browser-only deployment mode

Implement STATIC=1 environment variable to enable browser-only deployment
without proxy server infrastructure. Uses WS4KP_SERVER_AVAILABLE flag to
distinguish between server-backed and static deployments for proper URL
rewriting and User-Agent header handling.

- Add STATIC env var to skip proxy route registration at startup
- Inject WS4KP_SERVER_AVAILABLE flag via EJS template based on STATIC mode
- Update fetch.mjs to conditionally send User-Agent headers based on server availability
- Update url-rewrite.mjs to skip proxy rewriting when server is unavailable
- Use renderIndex helper for consistent template data across dev/prod modes
- Improve music playlist logging

Benefits of integrated approach:
- Single environment variable controls both server and client behavior
- Flag injection happens once at render time, not on every request
- No runtime HTML string manipulation overhead
- Clean separation between server-backed and static deployment logic
- Same codebase supports both deployment modes without duplication

Static mode (STATIC=1): Direct API calls to external services, no caching
Server mode (default): Local proxy with caching and API request observability

Dockerfile.server

@@ -0,0 +1,13 @@
+FROM node:24-alpine
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --legacy-peer-deps
+COPY . .
+
+RUN npm run build
+
+EXPOSE 8080
+
+ENV DIST=1
+CMD ["npm", "start"]

README.md

@@ -48,11 +48,20 @@ npm i
 node index.mjs
 ```
 
-To run via Docker: 
-```
+To run via Docker using a "static deployment" where everything happens in the browser (no server component):
+
+```bash
 docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp
 ```
-Open your web browser: http://localhost:8080/ 
+
+To run via Docker using a "server deployment" with a caching proxy server for multi-client performance and enhanced observability (the same as `npm start`):
+
+```bash
+docker build -f Dockerfile.server -t ws4kp-server .
+docker run -p 8080:8080 ws4kp-server
+```
+
+Open your web browser: http://localhost:8080/
 
 To run via Docker Compose (docker-compose.yaml):
 ```

gulp/publish-frontend.mjs

@@ -141,6 +141,7 @@ const compressHtml = async () => {
 	return src(htmlSources)
 		.pipe(ejs({
 			production: version,
+			serverAvailable: false,
 			version,
 			OVERRIDES,
 			query: {},

index.mjs

@@ -16,6 +16,12 @@ const stationInfo = JSON.parse(await readFile('./datagenerators/output/stations.
 const app = express();
 const port = process.env.WS4KP_PORT ?? 8080;
 
+// Set X-Weatherstar header globally for playlist fallback detection
+app.use((req, res, next) => {
+	res.setHeader('X-Weatherstar', 'true');
+	next();
+});
+
 // template engine
 app.set('view engine', 'ejs');
 
@@ -45,6 +51,19 @@ const hasQsVars = Object.entries(qsVars).length > 0;
 // turn the environment query string into search params
 const defaultSearchParams = (new URLSearchParams(qsVars)).toString();
 
+const renderIndex = (req, res, production = false) => {
+	res.render('index', {
+		production,
+		serverAvailable: !process.env?.STATIC, // Disable caching proxy server in static mode
+		version,
+		OVERRIDES,
+		query: req.query,
+		travelCities,
+		regionalCities,
+		stationInfo,
+	});
+};
+
 const index = (req, res) => {
 	// test for no query string in request and if environment query string values were provided
 	if (hasQsVars && Object.keys(req.query).length === 0) {
@@ -54,16 +73,8 @@ const index = (req, res) => {
 		res.redirect(307, url.toString());
 		return;
 	}
-	// return the standard page
-	res.render('index', {
-		production: false,
-		version,
-		OVERRIDES,
-		query: req.query,
-		travelCities,
-		regionalCities,
-		stationInfo,
-	});
+	// return the EJS template page in development mode (serve files from server directory directly)
+	renderIndex(req, res, false);
 };
 
 const geoip = (req, res) => {
@@ -106,25 +117,35 @@ const staticOptions = {
 };
 
 // Weather.gov API proxy (catch-all for any Weather.gov API endpoint)
-app.use('/api/', weatherProxy);
+// Skip setting up routes for the caching proxy server in static mode
+if (!process.env?.STATIC) {
+	app.use('/api/', weatherProxy);
 
-// Cache management DELETE endpoint to allow "uncaching" specific URLs
-app.delete(/^\/cache\/.*/, (req, res) => {
-	const path = req.url.replace('/cache', '');
-	const cleared = cache.clearEntry(path);
-	res.json({ cleared, path });
-});
+	// Cache management DELETE endpoint to allow "uncaching" specific URLs
+	app.delete(/^\/cache\/.*/, (req, res) => {
+		const path = req.url.replace('/cache', '');
+		const cleared = cache.clearEntry(path);
+		res.json({ cleared, path });
+	});
 
-// specific proxies for other services
-app.use('/radar/', radarProxy);
-app.use('/spc/', outlookProxy);
-app.use('/mesonet/', mesonetProxy);
+	// specific proxies for other services
+	app.use('/radar/', radarProxy);
+	app.use('/spc/', outlookProxy);
+	app.use('/mesonet/', mesonetProxy);
+
+	// Playlist route is available in server mode (not in static mode)
+	app.get('/playlist.json', playlist);
+}
 
 if (process.env?.DIST === '1') {
 	// Production ("distribution") mode uses pre-baked files in the dist directory
 	// 'npm run build' and then 'DIST=1 npm start'
 	app.use('/scripts', express.static('./server/scripts', staticOptions));
 	app.use('/geoip', geoip);
+
+	// render the EJS template in production mode (serve compressed files from dist directory)
+	app.get('/', (req, res) => { renderIndex(req, res, true); });
+
 	app.use('/', express.static('./dist', staticOptions));
 } else {
 	// Development mode serves files from the server directory: 'npm start'
@@ -133,7 +154,6 @@ if (process.env?.DIST === '1') {
 	app.use('/resources', express.static('./server/scripts/modules'));
 	app.get('/', index);
 	app.get('*name', express.static('./server', staticOptions));
-	app.get('/playlist.json', playlist);
 }
 
 const server = app.listen(port, () => {

server/scripts/modules/media.mjs

@@ -40,21 +40,32 @@ const scanMusicDirectory = async () => {
 };
 
 const getMedia = async () => {
+	let playlistSource = '';
+
 	try {
 		const response = await fetch('playlist.json');
 		if (response.ok) {
 			playlist = await response.json();
-		} else if (response.status === 404
-			&& response.headers.get('X-Weatherstar') === 'true') {
-			console.warn("Couldn't get playlist.json, falling back to directory scan");
+			playlistSource = 'from server';
+		} else if (response.status === 404 && response.headers.get('X-Weatherstar') === 'true') {
+			// Expected behavior in static deployment mode
 			playlist = await scanMusicDirectory();
+			playlistSource = 'via directory scan (static deployment)';
 		} else {
-			console.warn(`Couldn't get playlist.json: ${response.status} ${response.statusText}`);
 			playlist = { availableFiles: [] };
+			playlistSource = `failed (${response.status} ${response.statusText})`;
 		}
-	} catch (e) {
-		console.warn("Couldn't get playlist.json, falling back to directory scan");
+	} catch (_e) {
+		// Network error or other fetch failure - fall back to directory scanning
 		playlist = await scanMusicDirectory();
+		playlistSource = 'via directory scan (after fetch failed)';
+	}
+
+	const fileCount = playlist?.availableFiles?.length || 0;
+	if (fileCount > 0) {
+		console.log(`Loaded playlist ${playlistSource} - found ${fileCount} music file${fileCount === 1 ? '' : 's'}`);
+	} else {
+		console.log(`No music files found ${playlistSource}`);
 	}
 
 	enableMediaPlayer();

server/scripts/modules/utils/fetch.mjs

@@ -10,7 +10,7 @@ const safeJson = async (url, params) => {
 		}
 		// If caller didn't specify returnUrl, result is the raw API response
 		return result;
-	} catch (error) {
+	} catch (_error) {
 		// Error already logged in fetchAsync; return null to be "safe"
 		return null;
 	}
@@ -25,7 +25,7 @@ const safeText = async (url, params) => {
 		}
 		// If caller didn't specify returnUrl, result is the raw API response
 		return result;
-	} catch (error) {
+	} catch (_error) {
 		// Error already logged in fetchAsync; return null to be "safe"
 		return null;
 	}
@@ -40,7 +40,7 @@ const safeBlob = async (url, params) => {
 		}
 		// If caller didn't specify returnUrl, result is the raw API response
 		return result;
-	} catch (error) {
+	} catch (_error) {
 		// Error already logged in fetchAsync; return null to be "safe"
 		return null;
 	}
@@ -83,7 +83,11 @@ const fetchAsync = async (_url, responseType, _params = {}) => {
 	const checkUrl = new URL(_url, window.location.origin);
 	const shouldExcludeUserAgent = USER_AGENT_EXCLUDED_HOSTS.some((host) => checkUrl.hostname.includes(host));
 
-	if (!shouldExcludeUserAgent) {
+	// User-Agent handling:
+	// - Server mode (with caching proxy): Add User-Agent for all requests except excluded hosts
+	// - Static mode (direct requests): Only add User-Agent for api.weather.gov, avoiding CORS preflight issues with other services
+	const shouldAddUserAgent = !shouldExcludeUserAgent && (window.WS4KP_SERVER_AVAILABLE || _url.toString().match(/api\.weather\.gov/));
+	if (shouldAddUserAgent) {
 		headers['user-agent'] = 'Weatherstar 4000+; weatherstar@netbymatt.com';
 	}
 

server/scripts/modules/utils/url-rewrite.mjs

@@ -8,6 +8,10 @@ const rewriteUrl = (_url) => {
 	// Handle both string URLs and URL objects
 	const url = typeof _url === 'string' ? new URL(_url) : new URL(_url.toString());
 
+	if (!window.WS4KP_SERVER_AVAILABLE) {
+		return url;
+	}
+
 	// Rewrite the origin to use local proxy server
 	if (url.origin === 'https://api.weather.gov') {
 		url.protocol = window.location.protocol;

views/index.ejs

@@ -22,6 +22,9 @@
 	<link rel="prefetch" href="fonts/Star4000 Extended.woff" as="font" type="font/woff" crossorigin>
 	<link rel="prefetch" href="fonts/Star4000 Large.woff" as="font" type="font/woff" crossorigin>
 	<link rel="prefetch" href="fonts/Star4000 Small.woff" as="font" type="font/woff" crossorigin>
+	<% if (typeof serverAvailable !== 'undefined' && serverAvailable) { %>
+	<script>window.WS4KP_SERVER_AVAILABLE=true;</script>
+	<% } %>
 
   <% if (production) { %>
   <link rel="stylesheet" type="text/css" href="resources/ws.min.css?_=<%=production%>" />