🖥️ Installation

Hardware Requirements

Raspberry Pi

The Raspberry Pi is the most popular way to run OpenHamClock as a dedicated shack display. The setup script handles everything: Node.js, the app itself, a systemd service for auto-start, and optionally a full kiosk mode that launches Chromium fullscreen on boot.

Pi with kiosk display (recommended)

Use this if you have a monitor connected directly to the Pi and want a standalone clock/dashboard that powers up automatically with the shack.

1. Flash your SD card with Raspberry Pi OS Bookworm

   Use Raspberry Pi Imager. Choose Raspberry Pi OS (64-bit) with desktop. Enable SSH in the Advanced Options if you want remote access. A 32 GB card is plenty.

2. Boot the Pi and open a terminal

   Either connect a keyboard/monitor directly, or SSH in: ssh pi@raspberrypi.local

3. Run the setup script with kiosk mode

   bash Copy

   $ curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/scripts/setup-pi.sh | bash -s -- --kiosk

   The script will install Node.js, clone the repository, install dependencies, create a systemd service, and configure Chromium to launch fullscreen on boot. It takes about 5–10 minutes on a Pi 4.

4. Edit your .env file

   bash Copy

   $ nano ~/openhamclock/.env

   Set at minimum: CALLSIGN and LOCATOR. Save with Ctrl+O, exit with Ctrl+X.

5. Reboot

   bash Copy

   $ sudo reboot

   The Pi will boot directly into the OpenHamClock dashboard fullscreen. No login screen, no desktop — just the clock.

Pi as a headless server

Use this if you want to run OpenHamClock on a Pi tucked away in the shack and access it from other devices (a laptop, tablet, or second monitor) over your LAN.

$ curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/scripts/setup-pi.sh | bash -s -- --server

Then add HOST=0.0.0.0 to .env so the server listens on all interfaces. Access it from any device on your network at http://<pi-ip>:3000.

Managing the systemd service

# Check status
$ sudo systemctl status openhamclock

# View live logs
$ sudo journalctl -u openhamclock -f

# Restart after editing .env
$ sudo systemctl restart openhamclock

# Stop
$ sudo systemctl stop openhamclock

Docker / Docker Compose

The Docker image is the cleanest way to run a permanent local install on any machine. Everything is bundled — no Node.js, no npm, no system-level dependencies.

Quick start with Docker Compose

1. Create a project folder and download the Compose file

   bash Copy

   $ mkdir openhamclock && cd openhamclock
   $ curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/docker-compose.yml -o docker-compose.yml

2. Create your .env file

   .env Copy

   CALLSIGN=K0CJH
   LOCATOR=DM79
   # HOST=0.0.0.0   ← uncomment for LAN access

3. Start in detached mode

   bash Copy

   $ docker compose up -d

Ports exposed by the container

Updating Docker

$ docker compose pull
$ docker compose up -d

Windows

The recommended Windows path is Docker Desktop — follow the Docker section above. Docker Desktop gives you a native GUI for managing the container and handles WSL2 automatically.

Native Windows install (no Docker)

If you prefer not to use Docker, OpenHamClock runs natively on Windows via Node.js.

1. Install Node.js v22 LTS

   Download the Windows installer from nodejs.org. Accept all defaults. Restart your terminal after installation.

2. Install Git for Windows

   Download from git-scm.com if not already installed.

3. Clone and start

   PowerShell Copy

   PS> git clone https://github.com/accius/openhamclock.git
   PS> cd openhamclock
   PS> npm ci
   PS> npm start

Electron desktop app

OpenHamClock can also run as a native desktop window (no browser needed) using Electron:

$ npm run electron

macOS & Linux

Same steps as Option C in the Quick Start. For a permanent background service on Linux:

$ curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/scripts/setup-linux.sh | bash -s -- --service

This installs OpenHamClock and registers a systemd service that starts automatically on boot. Manage it the same way as the Pi service (see above).

Cloud Deployment — Railway

Railway is the easiest way to run OpenHamClock in the cloud — accessible from anywhere, no home server required. The free tier is usually sufficient for a single-user personal instance.

1. Fork the repository on GitHub

   Visit github.com/accius/openhamclock and click Fork. You need your own copy so Railway can deploy it.

2. Create a Railway project from your fork

   Log in at railway.app, click New Project → Deploy from GitHub repo, and select your fork. Railway detects the Dockerfile automatically.

3. Set environment variables in Railway dashboard

   In the Railway service settings, go to Variables and add at minimum:

   Railway Variables Copy

   CALLSIGN=K0CJH
   LOCATOR=DM79
   HOST=0.0.0.0
   TRUST_PROXY=true

4. Deploy and open the public URL

   Railway provides a public *.railway.app URL. Open it in your browser — your dashboard is live.

Updating & Upgrading

OpenHamClock follows a weekly release cycle. Updates are always backwards-compatible — your .env is never overwritten.

Git clone install (Pi / Linux / macOS)

$ cd ~/openhamclock
$ bash scripts/update.sh

The update script: backs up your .env, pulls the latest code, rebuilds the frontend, restores your settings, and restarts the service.

Docker

$ docker compose pull && docker compose up -d

Auto-update (optional)

Add these to your .env to have OpenHamClock check for updates automatically:

AUTO_UPDATE_ENABLED=true
AUTO_UPDATE_INTERVAL_MINUTES=60
AUTO_UPDATE_EXIT_AFTER=true   # systemd/pm2 will restart after update