Update README to clarify deployment modes and music handling

- Add clear distinction between Server and Static deployment modes - Restructure run instructions with specific npm commands and their purposes - Clarify Docker deployment scenarios (static vs server, with examples) - Rewrite music section to explain server-side vs browser-side playlist generation
2026-04-14 15:49:31 -07:00 · 2025-06-26 20:39:18 -04:00
parent 517cafe40a
commit 17585e97c4
1 changed files with 128 additions and 34 deletions
--- a/README.md
+++ b/README.md
@@ -39,32 +39,89 @@ This project is tightly coupled to [NOAA's Weather API](https://www.weather.gov/
 If you would like to display weather information for international locations (outside of the USA), please checkout a fork of this project created by [@mwood77](https://github.com/mwood77):
 - [`ws4kp-international`](https://github.com/mwood77/ws4kp-international)

+## Deployment Modes
+
+WeatherStar 4000+ supports two deployment modes:
+
+### Server Deployment (Recommended)
+
+* Includes Node.js server with caching proxy for better performance (especially when running on a local server for multiple clients)
+* Server-side request deduplication and caching
+* Weather API observability and logging
+* Used by: `npm start`, `DIST=1 npm start`, and `Dockerfile.server`
+
+### Static Deployment
+
+* Pure client-side deployment using nginx to serve static files
+* All API requests are made directly from each browser to the weather services
+* Browser-based caching
+* Used by: static file hosting and default `Dockerfile`
+
 ## Run Your WeatherStar
-To run via Node locally:
-```
+
+Ensure you have Node installed. Clone the repository:
+```bash
 git clone https://github.com/netbymatt/ws4kp.git
 cd ws4kp
-npm i
-node index.mjs
+npm install
 ```

-To run via Docker using a "static deployment" where everything happens in the browser (no server component):
+### Development Mode (individual JS files, easier debugging)
+```bash
+npm start
+```
+
+### Development Mode without proxy caching
+```bash
+STATIC=1 npm start
+```
+
+### Production Mode (minified/concatenated JS, faster loading)
+```bash
+npm run build
+DIST=1 npm start
+```
+
+### Production Mode without proxy caching (simulates static Docker deployment)
+```bash
+npm run build
+STATIC=1 DIST=1 npm start
+```
+
+For all modes, access WeatherStar by going to: http://localhost:8080/
+
+### Key Differences
+
+**Development Mode (`npm start`):**
+- Uses individual JavaScript module files served directly
+- Easier debugging with source maps and readable code
+- Slower initial load (many HTTP requests for individual files)
+- Live file watching and faster development iteration
+
+**Production Mode (`DIST=1 npm start`):**
+- Uses minified and concatenated JavaScript bundles
+- Faster initial load (fewer HTTP requests, smaller file sizes)
+- Optimized for performance with multiple clients
+- Requires `npm run build` to generate optimized files
+
+### Docker Deployments
+
+To run via Docker using a "static deployment" where everything happens in the browser (no server component, like STATIC=1):

 ```bash
 docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp
 ```

-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`):
+To run via Docker using a "server deployment" with a caching proxy server for multi-client performance and enhanced observability (like `npm run build; DIST=1 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 (shown here in static deployment mode):

-To run via Docker Compose (docker-compose.yaml):
-```
+```yaml
 ---
 services:
  ws4kp:
@@ -82,26 +139,33 @@ services:
    restart: unless-stopped
 ```

-### Serving static files
-The app can be served as a static set of files on any web server. Run the provided gulp task to create a set of static distribution files:
-```
+### Serving a static app
+
+There are several ways to deploy WeatherStar as a static app that runs entirely in the browser:
+
+**Manual static hosting (Apache, nginx, CDN, etc.):**
+Build static distribution files for upload to any web server:
+
+```bash
 npm run build
 ```
-The resulting files will be in the /dist folder in the root of the project. These can then be uploaded to a web server for hosting, no server-side scripting is required.

-When using the provided Docker image, the browser will generate `playlist.json`
-on the fly by scanning the `/music` directory served by nginx. The image
-intentionally omits this file so the page falls back to scanning the directory.
-Simply bind mount your music folder and the playlist will be created
-automatically. If no files are found in `/music`, the built in tracks located in
-`/music/default/` will be used instead.
+The resulting files in `/dist` can be uploaded to any web server; no server-side scripting is required.

-The nginx configuration also sets the `X-Weatherstar: true` header on all
-responses. This uses `add_header ... always` so the header is sent even for
-404 responses. When `playlist.json` returns a 404 with this header present, the
-browser falls back to scanning the `/music` directory. If you host the static
-files elsewhere, be sure to include this header so the playlist can be generated
-automatically.
+**Docker static deployment:**
+The default Docker image uses nginx to serve pre-built static files:
+
+```bash
+docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp
+```
+
+**Node.js in static mode:**
+Use the Node.js server as a static file host without the caching proxy:
+
+```bash
+STATIC=1 npm start          # Use Express to serve development files
+STATIC=1 DIST=1 npm start   # Use Express to serve (minimized) production files
+```

 ## What's different

@@ -152,16 +216,42 @@ I've used AI tools to create WeatherStar-inspired music tracks that are unencumb
 If you're looking for the original music that played during forecasts [TWCClassics](https://twcclassics.com/audio/) has thorough documentation of playlists.

 ### Customizing the music
-Placing .mp3 files in the `/server/music` folder will override the default music included in the repo. Subdirectories will not be scanned. When weatherstar loads in the browser it will load a list if available files and randomize the order when it starts playing. On each loop through the available tracks the order will again be shuffled. If you're using the static files method to host your WeatherStar music is located in `/music`.

-If using Docker, you can bind mount a local folder containing your music files.
-Mount the folder at `/usr/share/nginx/html/music` so the browser can read the
-directory listing and build the playlist automatically. If there are no `.mp3`
-files in `/music`, the built in tracks from `/music/default/` are used.
+WeatherStar 4000+ supports background music during forecast playback. The music behavior depends on how you deploy the application:
+
+#### Express server modes (`npm start`, `DIST=1 npm start`, or `Dockerfile.server`)
+
+When running with Node.js, the server generates a `playlist.json` file by scanning the `./server/music` directory for `.mp3` files. If no files are found in `./server/music`, it falls back to scanning `./server/music/default/`. The playlist is served dynamically at the `/playlist.json` endpoint.
+
+**Adding your own music:** Place `.mp3` files in `./server/music/`
+
+**Docker server example:**
+```bash
+docker build -f Dockerfile.server -t ws4kp-server .
+docker run -p 8080:8080 -v /path/to/local/music:/app/server/music ws4kp-server
 ```
+
+#### Static hosting modes (default `Dockerfile`, nginx, Apache, etc.)
+
+When hosting static files, there are two scenarios:
+
+**Static Docker deployment:** The build process creates a `playlist.json` file with default tracks, but the Docker image _intentionally_ removes it to force browser-based directory scanning. The browser attempts to fetch `playlist.json`, receives a 404 response with the `X-Weatherstar` header, which causes it to  fallback to scanning the `music/` directory.
+
+**Manual static hosting:** If you build and upload the files yourself (`npm run build`), `playlist.json` will contain the default tracks unless you customize `./server/music/` before building.
+
+For directory scanning to work properly:
+* Your web server must generate directory listings for the `music/` path
+* Your web server must set the `X-Weatherstar: true` header (the provided nginx configuration does this)
+
+**Adding your own music:** Place `.mp3` files in `music/` (or bind mount to `/usr/share/nginx/html/music` for Docker)
+
+**Docker static example:**
+```bash
 docker run -p 8080:8080 -v /path/to/local/music:/usr/share/nginx/html/music ghcr.io/netbymatt/ws4kp
 ```

+Subdirectories will not be scanned. When WeatherStar loads in the browser, it randomizes the track order and reshuffles on each loop through the playlist.
+
 ### Music doesn't auto play
 Ws4kp is muted by default, but if it was unmuted on the last visit it is coded to try and auto play music on subsequent visits. But, it's considered bad form to have a web site play music automatically on load, and I fully agree with this. [Chrome](https://developer.chrome.com/blog/autoplay/#media_engagement_index) and [Firefox](https://hacks.mozilla.org/2019/02/firefox-66-to-block-automatically-playing-audible-video-and-audio/) have extensive details on how and when auto play is allowed.

@@ -181,9 +271,13 @@ Thanks to the WeatherStar community for providing these discussions to further e
 * [ws4channels](https://github.com/rice9797/ws4channels) A Dockerized Node.js application to stream WeatherStar 4000 data into Channels DVR using Puppeteer and FFmpeg.

 ## Customization
-A hook is provided as `/server/scripts/custom.js` to allow customizations to your own fork of this project, without accidentally pushing your customizations back upstream to the git repository. A sample file is provided at `/server/scripts/custom.sample.js` and should be renamed to `custom.js` activate it.

-When using Docker, mount your `custom.js` file to `/usr/share/nginx/html/scripts/custom.js` to customize the static build.
+A hook is provided as `server/scripts/custom.js` to allow customizations to your own fork of this project, without accidentally pushing your customizations back upstream to the git repository. A sample file is provided at `server/scripts/custom.sample.js` and should be renamed to `custom.js` activate it.
+
+When using Docker:
+
+* **Static deployment**: Mount your `custom.js` file to `/usr/share/nginx/html/scripts/custom.js`
+* **Server deployment**: Mount your `custom.js` file to `/app/server/scripts/custom.js`

 ## Issue reporting and feature requests