Skip to content

openhamclock

Community continuation of HamClock as a browser dashboard — grey line, propagation, spots, satellites

What it does

Serves a live station dashboard in your browser: a world map with the grey line, solar and geomagnetic indices, band-condition predictions, DX cluster and POTA spots, satellite passes, and live decodes from WSJT-X on the same machine. It is the community's continuation of HamClock after its author became a Silent Key in January 2026, rewritten as a web application so it runs on anything with a browser — a shack PC, a Pi driving a wall display, or a phone on the same network if you choose to allow that.

Why you would want it

It is the at-a-glance answer to "which band should I be on right now", and the more active of the two maintained HamClock successors by a wide margin (Q-006). The alternative is hamclock-next, an SDL2 rewrite that keeps the original's look and runs as an ordinary desktop program with no Node involved; both are carried, and propagation ships this one as the default.

Before it will work

Node.js 20.19 or newer from your distribution — hammunition installs nodejs and npm from the archive and refuses, naming the version, if what is offered is too old. Debian 13 and Parrot ship 20.19 and Ubuntu 26.04 ships 22.22; Ubuntu 24.04 ships 18.19 and is refused — the server needs require() of an ES module, which arrived in 20.19, and on 18 it builds and then dies at its first start (measured). The engine will not fetch a newer Node for you (D-037); on 24.04 the answer is hamclock-next, or a newer release of the distribution. A network connection at install time: the build fetches about 730 packages from registry.npmjs.org, each checked against the lock file that arrives inside the sha256-verified source archive; nothing else is fetched and no package's install scripts run. After installing, edit ~/.local/share/hammunition/node/openhamclock/.env and set CALLSIGN and LOCATOR — the first start creates that file from upstream's example with N0CALL and FN31 in it, and the dashboard is centred on the wrong hemisphere until you do. A reinstall or update keeps your .env. The engine does not fill those values in yet (station config, D-035, is absolute-path config files only so far); this is a hand step and the profile says so.

How it installs

  • node (needs Node 20.19+ from the distribution; dependencies fetched from registry.npmjs.org against the lock file) from https://github.com/accius/openhamclock/archive/refs/tags/v26.7.3.tar.gz
  • build dependencies: nodejs, npm, patch
  • Needs Node.js 20.19 or newer from the distribution's own nodejs package — the engine never fetches Node from NodeSource or nodejs.org, and refuses at plan time when the archive's Node is absent or too old. Ubuntu 24.04's 18.19 is too old: it builds, then the server dies at start (ERR_REQUIRE_ESM; measured 2026-09-02), so that target is refused. The build downloads its dependency closure from registry.npmjs.org, verified against the lock file. Built and run 2026-09-02 on Debian 13 (Node 20.19.2, npm 9.2).

Known problems

Upstream ignores its own HOST setting, so this build patches one line. v26.7.0 reads HOST, prints it, and then listens on 0.0.0.0 anyway — measured, not assumed — which would put a dashboard with an open write API on every interface of a machine that may also carry security tooling. The patch makes app.listen use HOST, and it is in the manifest for review. With it, the bind is whatever .env says: the wrapper sets HOST=127.0.0.1 but openhamclock's own .env loader overrides the environment, and the .env it generates says HOST=localhost, which Node binds as ::1 — loopback either way, and why the launcher opens http://localhost:3001 rather than an IPv4 address. Set HOST=0.0.0.0 in .env and the dashboard is reachable from your whole network, which is what you want for a wall display and not what you want on a laptop; the choice is yours and it is one line, and set API_WRITE_KEY there if you make it. The same override applies to PORT: the launcher opens :3001, so change it in .env and the browser tab points at the old one. UDP 2237 listens on every interface regardless — the WSJT-X integration binds 0.0.0.0 at start and HOST does not govern it; set WSJTX_ENABLED=false in .env if you do not run WSJT-X, or want nothing listening. The server opens outbound connections the moment it starts — a persistent telnet session to telnet.reversebeacon.net:7000 for RBN spots among them, logging in with your CALLSIGN, or with the project's own K0CJH-3 while .env still says N0CALL (upstream does this deliberately, to keep invalid logins off other people's infrastructure); one more reason to set your callsign before the first start. Propagation runs in "Standalone mode": upstream's build normally downloads an ITU P.533 model as WASM from a moving release tag with a checksum from the same place, which is not a pin, so this build skips it and the server uses its built-in model. A pinned WASM may be carried later as a verified artefact. The auto-update setting does nothing here: AUTO_UPDATE_ENABLED expects a git clone; leave it false and update through hammunition, which rebuilds from the next pinned release. The runtime tree is about 180 MB. Two commands land on your PATH: openhamclock opens the dashboard in a terminal and a browser; openhamclock-server is the bare server for a headless box or a systemd unit of your own.

Keeping it current

  • probe: github release (accius/openhamclock)
  • strategy: rebuild
  • Upstream releases monthly, on the first Tuesday (its CHANGELOG says so; the changelog itself is frozen and release notes live on GitHub). A rebuild keeps the operator's .env.

Source: catalog/packages/openhamclock.yaml