markmental/ws4kp-linhanced
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README update + make server observations code a bit more clear in allowed key conditions
Some checks are pending
build-docker / Build Image (push) Waiting to run
Details

Browse source
This commit is contained in:
mrkmntal 2026-04-09 15:59:23 -04:00
commit 97b59a6bd4
2 changed files with 164 additions and 339 deletions
Download patch file Download diff file Expand all files Collapse all files

499
README.md
View file

@ -4,30 +4,60 @@
`ws4kp-linhanced` is a Linux-focused fork of [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) by `markmental`.
## About
It keeps the stronger, more stable foundation of the original `ws4kp` project while selectively incorporating international weather support and global map ideas from [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international). The goal is not to become a kitchen-sink weather platform. The goal is a leaner, maintainable, Linux-oriented WeatherStar fork with a clear identity.
This fork keeps the classic WeatherStar-style experience and stable base architecture from the original `ws4kp` project, while selectively integrating international weather support and other practical improvements. It is not intended to be a perfect hardware emulation of the WeatherStar 4000. If you want a more exact recreation of the original hardware behavior, see the [WS4000 Simulator](http://www.taiganet.com/).
This fork also explicitly embraces Slackware Linux / `weatherstar4k` branding as part of its mission. Broad platform neutrality is not a design goal here.
This fork also explicitly adopts Slackware Linux `weatherstar4k` branding as part of its mission. The goal is not broad platform neutrality. The goal is a lean, self-hostable, Linux-oriented weatherstar fork with a strong visual identity and a codebase that stays practical to maintain.
## What This Fork Is
## About This Fork
`ws4kp-linhanced` is a retro weather display project that preserves the classic WeatherStar-style feel while updating the data sources and map stack for modern use.
This project is based on:
This fork is built around a few priorities:
* [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the core WeatherStar implementation and the more stable upstream foundation.
* [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for the Open-Meteo international weather direction and some global map ideas.
* keep the classic WeatherStar presentation and pacing intact where practical
* support international locations without dragging in unnecessary feature creep
* prefer a stable, understandable codebase over maximum feature count
* lean into Linux-oriented branding and integrations where they add character and usefulness
This fork intentionally diverges from `ws4kp-international`. That project proved out the international weather concept, but this fork aims to keep a narrower scope and avoid the feature creep that can make ongoing work harder. The original `ws4kp` codebase provided a better base for that approach, so this fork builds from there and pulls in only the parts that fit.
It is not intended to be a perfect hardware emulation of the original WeatherStar 4000. If you want a project aimed more directly at hardware-faithful behavior, see the [WS4000 Simulator](http://www.taiganet.com/).
## Current Direction
## Why This Fork Exists
This fork is focused on:
This fork exists because the original `ws4kp` codebase provided the best overall base to keep working from, but it remained too tightly tied to US-only weather sources. At the same time, `ws4kp-international` proved that Open-Meteo and global map support were viable, but it grew in directions that felt heavier and harder to maintain.
* preserving the classic WeatherStar feel while staying maintainable
* Linux-first identity and presentation
* Open-Meteo-based international weather support for the core forecast screens
* global radar and global regional observations on the newer map stack
* pragmatic feature additions instead of broad platform expansion
This fork sits in the middle on purpose:
* more international than upstream `ws4kp`
* leaner and narrower in scope than `ws4kp-international`
* more explicitly Linux-focused than either
## Fork Lineage
This project builds on the work of:
* [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the core WeatherStar implementation and overall application structure
* [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for Open-Meteo international weather direction and some global-map concepts
This fork intentionally diverges from `ws4kp-international`. It selectively adapts the parts that fit this project and leaves behind the parts that would make the codebase harder to keep stable.
## Current Features
Major features currently in this fork:
* Open-Meteo-based international weather for the core forecast screens
* ArcGIS-powered international location search and reverse geocoding
* global RainViewer radar on a cached world basemap
* global `Regional Observations` on the newer map stack
* Travel Forecast rebuilt around region buckets with a global fallback
* live theme switching with auto-discovered theme folders
* Server Observations powered by [fastfetch](https://github.com/fastfetch-cli/fastfetch)
* server-side caching proxy for Open-Meteo, RainViewer metadata, and ArcGIS basemap tiles
* static-build path fixes for subdirectory deployment
Some NOAA-only products are still retained where they remain useful and there is no replacement yet:
* Hazards
* SPC Outlook
## Themes
@ -35,41 +65,26 @@ This fork is focused on:
Current themes include:
* `Default`: the standard WeatherStar 4000+ asset set.
* `oceanview`: based on the Oceanview Weather Channel presentation from the Eventide Media Center analog horror series.
* `slackware`: based on the Oceanview theme, but with the Slackware Linux badge/logo treatment.
* `Default`: the standard WeatherStar 4000+ asset set
* `oceanview`: based on the Oceanview Weather Channel presentation from the Eventide Media Center analog horror series
* `slackware`: based on the Oceanview theme, but with the Slackware Linux badge/logo treatment
At the moment, theming covers the major background assets and the corner logo. Additional theme asset overrides can be added by placing matching files in `themes/<theme-name>/`.
Current themed assets include:
## What's your motivation
* `logo-corner.png`
* `1.png`
* `1-chart.png`
* `2.png`
* `3.png`
* `4.png`
* `5.png`
Nostalgia, Linux affinity, and an interest in keeping a practical retro weather display alive without turning it into a sprawling platform.
### Included technology
This fork still keeps the original project's straightforward architecture and relatively low dependency surface so it stays approachable to modify.
From a learning standpoint, this codebase makes use of a lot of different methods and technologies common on the internet including:
* The [Open-Meteo API](https://open-meteo.com/) for core forecast data.
* NOAA APIs and products where legacy US-only displays still require them.
* ES 6 functionality
* Arrow functions
* Promises
* Async/await and parallel loading of forecast resources
* Classes and extensions
* Javascript modules
* Separation between API code and user interface code
* Use of a modern date parsing library [luxon](https://moment.github.io/luxon/)
* Server-side proxy caching plus browser/static asset caching
* [fastfetch](https://github.com/fastfetch-cli/fastfetch) for the Linux-oriented Server Observations display
* Very straight-forward hand written HTML
* Build system integration (Gulp, Webpack) to reduce the number of scripts that need to be loaded
* Hand written CSS made easier to mange with SASS
* A linting library to keep code style consistent
Additional themes can be added by creating a subdirectory under `themes/` with matching override filenames.
## Quick Start
Ensure you have Node installed.
```bash
git clone <your fork url here>
cd ws4kp-linhanced
@ -77,352 +92,160 @@ npm install
npm start
```
Open your browser and navigate to https://localhost:8080
Then open:
## Does ws4kp-linhanced work outside of the USA?
```text
http://localhost:8080/
```
Yes for the core forecast screens, and more than that.
## Running Modes
The main weather flow now uses Open-Meteo, so search, current conditions, hourly, local forecast, extended forecast, almanac, travel forecast, radar, and regional observations all work internationally.
This fork supports two main runtime styles.
Some legacy displays still rely on [NOAA's Weather API](https://www.weather.gov/documentation/services-web-api) and remain available only for United States locations for now:
### Server Mode
* Hazards
* SPC Outlook
Recommended for normal use.
This fork no longer treats `ws4kp-international` as a drop-in upstream. Instead, it selectively incorporates the Open-Meteo international weather work while keeping a leaner feature set and a more stable base.
Earlier international work on this idea was explored in a fork created by [@mwood77](https://github.com/mwood77):
- [`ws4kp-international`](https://github.com/mwood77/ws4kp-international)
## Deployment Modes
`ws4kp-linhanced` 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`
## Other methods to run ws4kp-linhanced
### Development Mode (individual JS files, easier debugging)
```bash
npm start
```
### Development Mode without proxy caching
```bash
STATIC=1 npm start
```
This mode includes:
### Production Mode (minified/concatenated JS, faster loading)
```bash
npm run build
DIST=1 npm start
```
* Express server entry point
* proxying and caching for weather/map requests
* Fastfetch-backed Server Observations
* better shared performance when multiple clients use the same instance
### Static Mode
Useful if you want to serve the built files directly.
### Production Mode without proxy caching (simulates static Docker deployment)
```bash
npm run build
STATIC=1 DIST=1 npm start
```
For all modes, access `ws4kp-linhanced` 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 (like `npm run build; DIST=1 npm start`):
```bash
docker build -f Dockerfile.server -t ws4kp-server .
docker run -p 8080:8080 ws4kp-server
```
To run via Docker Compose (shown here in static deployment mode):
```yaml
---
services:
ws4kp:
image: ghcr.io/netbymatt/ws4kp
container_name: ws4kp
environment:
# Each argument in the permalink URL can become an environment variable on the Docker host by adding WSQS_
# Following the "Sharing a Permalink" example below, here are a few environment variables defined. Visit that section for a
# more complete list of configuration options.
- WSQS_latLonQuery=Orlando International Airport Orlando FL USA
- WSQS_hazards_checkbox=false
- WSQS_current_weather_checkbox=true
ports:
- 8080:8080 # change the first 8080 to meet your local network needs
restart: unless-stopped
```
### 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:
Or upload the generated `dist/` directory to your web server after running:
```bash
npm run build
```
The resulting files in `/dist` can be uploaded to any web server; no server-side scripting is required.
The static build has been adjusted so frontend-generated paths no longer assume deployment at `/`, which makes subdirectory hosting more practical.
**Docker static deployment:**
The default Docker image uses nginx to serve pre-built static files:
## International Support
```bash
docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp
Core forecast functionality works internationally.
That currently includes:
* Current Conditions
* Hourly Forecast
* Hourly Graph
* Local Forecast
* Extended Forecast
* Almanac
* Travel Forecast
* Local Radar
* Regional Observations
Legacy NOAA-only screens still remain US-specific where applicable.
## Settings And Customization
Important settings and customization features include:
* playback speed
* widescreen mode
* kiosk mode
* scan lines
* US vs metric units
* theme selection
* custom bottom scroll text
* display enable/disable checkboxes
### Permalinks
Display selections, location, and major settings can be shared or bookmarked through the built-in permalink feature.
### Kiosk Mode
Kiosk mode hides the surrounding controls and maximizes the display area for dedicated setups. It can be triggered from the UI or via permalink parameters.
### Custom Scroll Text
The bottom text crawl can be customized using the built-in custom text setting.
Multiple messages can be separated with `|` to rotate randomly.
Example:
```text
Welcome to Weatherstar|Thanks for watching
```
**Node.js in static mode:**
Use the Node.js server as a static file host without the caching proxy:
### Custom Hook
```bash
STATIC=1 npm start # Use Express to serve development files
STATIC=1 DIST=1 npm start # Use Express to serve (minimized) production files
A customization hook is available as:
```text
server/scripts/custom.js
```
## What's different
A sample file exists at:
This fork has diverged significantly from upstream in a few important ways:
* Core weather and forecast screens now use Open-Meteo instead of being tied entirely to weather.gov.
* Travel Forecast has been rebuilt on region buckets with a global fallback instead of remaining a US-only NOAA-driven screen.
* Local Radar now uses global RainViewer radar imagery on top of a cached world basemap instead of the older US-only radar path.
* Regional Forecast has been temporarily replaced by a global `Regional Observations` map display using nearby city observations on the new map stack.
* Latest Observations has been removed.
* Some NOAA-based displays are still retained where there is no equivalent replacement yet, especially Hazards and SPC Outlook.
* This fork explicitly embraces Linux and Slackware-flavored `weatherstar4k` branding instead of aiming for broad neutral presentation.
## Sharing a permalink (bookmarking)
Selected displays, the forecast city and widescreen setting are sticky from one session to the next. However if you would like to share your exact configuration or bookmark it, click the "Copy Permalink" (or get "Get Permalink") near the bottom of the page. A URL will be copied to your clipboard with all of you selected displays and location (or copy it from the page if your browser doesn't support clipboard transfers directly). You can then share this link or add it to your bookmarks.
Your permalink will be very long. Here is an example for the Orlando International Airport:
```text
server/scripts/custom.sample.js
```
https://weatherstar.netbymatt.com/?hazards-checkbox=false&current-weather-checkbox=true&latest-observations-checkbox=true&hourly-checkbox=false&hourly-graph-checkbox=true&travel-checkbox=false&regional-forecast-checkbox=true&local-forecast-checkbox=true&extended-forecast-checkbox=true&almanac-checkbox=false&spc-outlook-checkbox=true&radar-checkbox=true&settings-wide-checkbox=false&settings-kiosk-checkbox=false&settings-scanLines-checkbox=false&settings-speed-select=1.00&settings-units-select=us&latLonQuery=Orlando+International+Airport%2C+Orlando%2C+FL%2C+USA&latLon=%7B%22lat%22%3A28.431%2C%22lon%22%3A-81.3076%7D
```
You can also build your own permalink. Any omitted settings will be filled with defaults. Here are a few examples:
```
https://weatherstar.netbymatt.com/?latLonQuery=Orlando+International+Airport
https://weatherstar.netbymatt.com/?kiosk=true
https://weatherstar.netbymatt.com/?settings-units-select=metric
```
### Kiosk mode
Kiosk mode can be activated by a checkbox on the page. This will start Weatherstar in a fullscreen-like view without the play/volume/etc toolbar and scaled to fill the entire space. This does not activate the browser's fullscreen or kiosk mode. Those can only be activated by user interaction or by launching the browser with specific parameters such as `--start-fullscreen` or `--kiosk`.
When using kiosk mode (via the checkbox), there will be no way to exit the fullscreen-like view of weatherstar. Reloading the page should remove the kiosk checkbox and return you to the normal view. This is deliberate as a browser's kiosk mode it intended not to be exited or significantly modified. A separate full-screen icon is available in the tool bar to go full-screen on a laptop or mobile browser.
It's also possible to enter kiosk mode using a permalink. First generate a [Permalink](#sharing-a-permalink-bookmarking), then to the end of it add `&kiosk=true`. Opening this link will load all of the selected displays included in the Permalink, enter kiosk mode immediately upon loading and start playing the forecast.
### Default query string parameters (environment variables)
When serving this via the built-in Express server, it's possible to define environment variables that direct the user to a default set of parameters (like the [Permalink](#sharing-a-permalink-bookmarking) above). If a user requests the root page at `http://localhost:8080/` the query string provided by environment variables will be appended to the url thus providing a default configuration.
Environment variables can be added to the command line as usual, or via a .env file which is parsed with [dotenv](https://github.com/motdotla/dotenv). Both methods have the same effect.
Environment variables that are to be added to the default query string are prefixed with `WSQS_` and then use the same key/value pairs generated by the [Permalink](#sharing-a-permalink-bookmarking) above, with the `- (dash)` character replaced by an `_ (underscore)`. For example, if you wanted to turn the travel forecast on, you would find `travel-checkbox=true` in the permalink, its matching environment variable becomes `WSQS_travel_checkbox=true`.
When using the Docker container, these environment variables are read on container start-up to generate the static redirect HTML.
## Settings
**Speed:** Controls the playback speed multiplier of the displays, from "Very Fast" (1.5x) to "Very Slow" (0.5x) with "Normal" being 1x
**Widescreen:** Stretches the background to 16:9 to avoid "pillarboxing" on modern displays
**Kiosk:** Immediately activates kiosk mode, which hides all settings. Exit by refreshing the page or using `Ctrl-K`. (Kiosk mode is similar to clicking the "Fullscreen" icon, but scales to the current browser viewport instead of activating the browser's actual "Fullscreen" mode.)
**Sticky Kiosk:** When enabled, stores the kiosk mode preference in local storage so the page automatically enters kiosk mode (maximizing the size of the main weather display without any settings) on subsequent visits. This feature is designed primarily for **iPhone and iPad users** who want to create a Home Screen app experience, since Mobile Safari doesn't support PWA installation via manifest.json or the Fullscreen API:
**For iOS/iPadOS (Mobile Safari):**
1. Tap the _Share_ icon and choose **Add to Home Screen**
2. Adjust the name as desired and tap **Add**
3. Launch the newly-created Home Screen shortcut
4. Configure all settings
5. Tap to enable **Sticky Kiosk**
6. _Make sure everything is configured exactly like you want it!_
7. Tap **Kiosk**
**For Android and Desktop browsers:** The included `manifest.json` file enables PWA (Progressive Web App) installation. To get the best app-like experience:
1. Configure all your settings first (ignore the "Kiosk" and "Sticky Kiosk" settings)
2. Create a permalink using the "Copy Permalink" feature and manually add `&kiosk=true` to the end
3. Open the edited permalink URL in your browser
4. Look for browser prompts to "Install" or "Add to Home Screen" from the kiosk-enabled URL
5. The PWA will launch directly into kiosk mode (without forcing kiosk mode when accessed from the browser)
For temporary fullscreen during regular browsing, use the fullscreen button in the toolbar.
**Important Notes:**
* **iOS/iPadOS limitations**: Mobile Safari strips all URL parameters when adding to Home Screen and runs shortcuts in an isolated environment with separate storage from the main Safari app
* After creating a Home Screen app on iOS or iPadOS and activating Kiosk mode, the only way to change settings is to delete the Home Screen shortcut and recreate it
* In situations where you _can_ edit a shortcut's URL, you can forcibly remove a "sticky" kiosk setting by adding `&kiosk=false` to the URL (or simply press `Ctrl-K` to exit kiosk mode if a keyboard is available)
**Scan Lines:** Enables a retro-style scan line effect
**Scan Lines Style:** Override the "auto" setting in case you prefer a different scale factor than what the automatic heuristics select for your browser and display
**Units:** Switches between US and metric units. (Note that some text-based products from the National Weather Service APIs contain embedded units that are not converted.)
**Volume:** Controls the audio level when music is enabled
## Music
The WeatherStar had wonderful background music from the smooth jazz and new age genres by artists of the time. Lists of the music that played are available by searching online, but it's all copyrighted music and would be difficult to provide as part of this repository.
The original WeatherStar atmosphere depended heavily on background music. This repo includes a small set of WeatherStar-inspired tracks, while keeping the total size manageable.
I've used AI tools to create WeatherStar-inspired music tracks that are unencumbered by copyright and are included in this repo. To keep the size down, I've only included 4 tracks. Additional tracks are in a companion repository [ws4kp-music](https://github.com/netbymatt/ws4kp-music).
If you want to use your own music, place `.mp3` files in:
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
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
```text
server/music/
```
#### Static hosting modes (default `Dockerfile`, nginx, Apache, etc.)
The application will build or serve a playlist from those files depending on the runtime mode.
When hosting static files, there are two scenarios:
## Build And Maintenance Notes
**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.
This fork tries to stay practical not only at runtime, but also in how it is maintained.
**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.
That includes:
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)
* keeping the codebase relatively small and understandable
* avoiding unnecessary build complexity where possible
* trimming or replacing dependencies when the benefit is low
* addressing build-step vulnerabilities instead of ignoring them
**Adding your own music:** Place `.mp3` files in `music/` (or bind mount to `/usr/share/nginx/html/music` for Docker)
Recent cleanup includes removing vulnerable build-only sourcemap tooling from the main build pipeline.
**Docker static example:**
```bash
docker run -p 8080:8080 -v /path/to/local/music:/usr/share/nginx/html/music ghcr.io/netbymatt/ws4kp
```
## Motivation
Subdirectories will not be scanned. When WeatherStar loads in the browser, it randomizes the track order and reshuffles on each loop through the playlist.
Part of the motivation is simple nostalgia: old Weather Channel presentation still has a very distinct charm.
### 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.
Chrome seems to be more lenient on auto play and will eventually let a site auto-play music if you're visited it enough recently and manually clicked to start playing music on each visit. It also has a flag you can add to the command line when launching Chrome: `chrome.exe --autoplay-policy=no-user-gesture-required`. This is the best solution when using Kiosk-style setup.
If you're unable to pre-set the play state before entering kiosk mode (such as with a home dashboard implementation) you can add the query string value below to the url. The browser will still follow the auto play rules outlined above.
```
?settings-mediaPlaying-boolean=true
```
## Community Notes
Thanks to the WeatherStar+ community for providing these discussions to further extend your retro forecasts!
* [Stream as FFMPEG](https://github.com/netbymatt/ws4kp/issues/37#issuecomment-2008491948)
* [Weather like it's 1999](https://blog.scottlabs.io/2024/02/weather-like-its-1999/) Raspberry pi, streaming, music and CRT all combined into a complete solution.
* [ws4channels](https://github.com/rice9797/ws4channels) A Dockerized Node.js application to stream WeatherStar 4000 data into Channels DVR using Puppeteer and FFmpeg.
* [SSL Certificates](https://github.com/netbymatt/ws4kp/issues/135) Discussion about how to host with an SSL certificate (enables geolocation).
* [Changing playlists](https://github.com/netbymatt/ws4kp/issues/138) Possible ways to automatically change the playlist on a schedule.
* [Customize Travel Forecast Cities](https://github.com/netbymatt/ws4kp/issues/146#issuecomment-3363940202)
## 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:
* **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`
### Custom text scroll
If you would like your Weatherstar to have custom scrolling text in the bottom blue bar, turn on the setting for `Enable RSS Feed/Text` and then enter text in the resulting text box. Then press set.
Tip: You can have Weatherstar select randomly between several text strings on each pass through the current conditions. Use a pipe character to separate string. `Welcome to Weatherstar|Thanks for watching`.
## Issue reporting and feature requests
Please do not report issues with api.weather.gov being down. It's a new service and not considered fully operational yet. I've also observed that the API can go down on a regional basis (based on NWS office locations). This means that you may have problems getting data for, say, Chicago right now, but Dallas and others are working just fine.
Before reporting an issue or requesting a feature please consider that this is not intended to be a perfect recreation of the WeatherStar 4000, it's a best effort that fits within what's available from the API and within a web browser.
Note: not all units are converted to metric, if selected. Some text-based products such as warnings are simple text strings provided from the national weather service and thus have baked-in units such as "gusts up to 60 mph." These values will not be converted.
## The full moon icon is broken
This is a known problem with the Ws4kp as it ages. It was a problem with the [actual Weatherstar hardware](https://youtu.be/rcUwlZ4pqh0?feature=shared&t=116) as well.
## Phone App
An Android app is in a closed beta test. It's nothing too special, just a wrapper for displaying the website in a browser.
You can get this functionality without an app on both Andriod and iOS by using the install or add to home screen feature of your browser.
iOS native app? No. I own zero Apple devices and thus have no way to develop, test, compile or verify myself to the app store. That application will have to come from the community.
## Related Projects
Not retro enough? Try the [Weatherstar 3000+](https://github.com/netbymatt/ws3kp)
## Use
Linking directly to the live web site at https://weatherstar.netbymatt.com is encouraged. As is using the live site for digital signage, home dashboards, streaming and public display. Please note the disclaimer below.
The other part is more practical. A Linux-friendly, self-hostable retro weather display is still a fun and useful thing to have around, especially when it stays light enough to keep hacking on without turning into an enormous platform project.
## Acknowledgements
This project is based on the work of [Mike Battaglia](https://github.com/vbguyny/ws4kp). It was forked from his work in August 2020.
This project builds on earlier work from the WeatherStar community and related forks.
* Mike Battaglia for the original project and all of the code which draws the weather displays. This code remains largely intact and was a huge amount of work to get exactly right. He's also responsible for all of the background graphics including the maps used in the application.
* The team at [TWCClassics](https://twcclassics.com/) for several resources.
* A [font](https://twcclassics.com/downloads.html) set used on the original WeatherStar 4000
* [Icon](https://twcclassics.com/downloads.html) sets
* Countless photos and videos of WeatherStar 4000 forecasts used as references.
* The growing list of contributors to this repository
Credits and thanks go to:
* [Mike Battaglia](https://github.com/vbguyny/ws4kp) for the original project lineage
* [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the upstream base this fork was built from
* [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for proving out the Open-Meteo international direction
* [TWCClassics](https://twcclassics.com/) for WeatherStar reference material, fonts, and icon resources
* the broader WeatherStar community for reference material and ongoing experimentation
## Disclaimer
This web site should NOT be used in life threatening weather situations, or be relied on to inform the public of such situations. The Internet is an unreliable network subject to server and network outages and by nature is not suitable for such mission critical use. If you require such access to NWS data, please consider one of their subscription services. The authors of this web site shall not be held liable in the event of injury, death or property damage that occur as a result of disregarding this warning.
This project should **not** be relied upon in life-threatening weather situations or as a mission-critical public weather information source.
The WeatherSTAR 4000 unit and technology is owned by The Weather Channel. This web site is a free, non-profit work by fans. All of the back ground graphics of this web site were created from scratch. The icons were created by Charles Abel and Nick Smith (http://twcclassics.com/downloads/icons.html) as well as by Malek Masoud. The fonts were originally created by Nick Smith (http://twcclassics.com/downloads/fonts.html).
Internet services fail, upstream data can be delayed, and browser-based applications are not a substitute for dedicated alerting systems.
The WeatherSTAR 4000 name and original technology belong to The Weather Channel. This project is a fan-made, non-commercial recreation and reinterpretation.

4
server/scripts/modules/serverobservations.mjs
View file

@ -10,6 +10,8 @@ const LINES_PER_PAGE = 4;
const PAGE_DURATION_MS = 7000;
const ALLOWED_KEYS = new Set(['OS', 'Kernel', 'Uptime', 'CPU', 'GPU', 'Memory', 'Disk']);
const isAllowedObservationKey = (key) => ALLOWED_KEYS.has(key) || key.startsWith('Disk');
const parseServerObservationLine = (line) => {
const trimmed = line.trim();
if (!trimmed) return null;
@ -20,7 +22,7 @@ const parseServerObservationLine = (line) => {
if (separatorIndex > 0) {
const key = trimmed.slice(0, separatorIndex).trim();
const value = trimmed.slice(separatorIndex + separator.length).trim();
if (key && value && ALLOWED_KEYS.has(key)) {
if (key && value && isAllowedObservationKey(key)) {
return { key, value };
}
}