Home › Quick Start
Section 02

⚡ Quick Start

Install

Three paths to a running dashboard — pick the one that fits your setup. No prerequisites needed for Option A.

Choose Your Path

Option What you need Time Best for
A — Browser Just a web browser 30 seconds Trying it out, no install
B — Docker Docker Desktop installed 2 minutes Any PC/Mac/Linux, persistent install
C — Node.js Node.js 20+ and Git 3 minutes Developers, Raspberry Pi, full control

Option A — Try it in the Browser

The fastest way to see OpenHamClock is the hosted version at openhamclock.com. It runs the same codebase as a self-hosted install, with all 30+ panels active.

  1. Open openhamclock.com in your browser

    The dashboard loads immediately. You will see a setup prompt asking for your callsign.

  2. Enter your callsign

    Type your amateur radio callsign (e.g. K0CJH). If you do not have a licence yet, use a well-known callsign like W1AW to explore.

  3. Enter your grid square

    A Maidenhead grid locator is a 4- or 6-character code (e.g. FN31 for New England). Not sure of yours? Find it at levinecentral.com/ham/grid_square.php — just click your location on the map.

  4. Explore the dashboard

    DX spots, space weather, and the world map are live immediately. Your settings are saved in your browser for next time.

ℹ️
WSJT-X and rig control require a self-hosted install

The hosted site cannot reach your local network. WSJT-X/FT8 integration and rig control (Rig Bridge) only work when OpenHamClock is running on your own machine or LAN. All other panels work fully on the hosted version.

Option B — Docker One-Liner

If you have Docker installed, this is the recommended way to run a permanent local install. No Node.js, no Git, no manual dependency management.

  1. Download the Docker Compose file
    bash 
    $ curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/docker-compose.yml -o docker-compose.yml
  2. Create your .env configuration file

    Create a file called .env in the same folder. At minimum, set your callsign and grid:

    .env 
    CALLSIGN=K0CJH
LOCATOR=DM79

    Replace K0CJH and DM79 with your own callsign and grid square. See Configuration for the full list of options.

  3. Start the container
    bash 
    $ docker compose up -d

    The first run downloads the image (about 250 MB) and starts the server.

  4. Open your browser

    Navigate to http://localhost:3000. Your dashboard is live.

💡
Accessing from other devices on your network

Add HOST=0.0.0.0 to your .env file and restart the container. Then open http://<your-pc-ip>:3000 from any device on your LAN — a tablet on the operating table, for example.

Option C — Local Node.js Install

The bare-metal approach. This is what you want for a Raspberry Pi, for development, or if you prefer not to use Docker. Requires Node.js 20 or later (v22 LTS recommended) and Git.

  1. Clone the repository
    bash 
    $ git clone https://github.com/accius/openhamclock.git
$ cd openhamclock
  2. Install dependencies
    bash 
    $ npm ci

    This installs exactly the versions in the lockfile. Takes 1–2 minutes on first run.

  3. Set your callsign and grid

    On first run, the server automatically copies .env.example to .env. Open .env in any text editor and set at minimum:

    .env 
    CALLSIGN=K0CJH
LOCATOR=DM79
  4. Start the server
    bash 
    $ npm start

  OpenHamClock v26.3.2
  Backend  → http://localhost:3001
  Frontend → http://localhost:3000
  Ready.

    Open http://localhost:3000 in your browser.

ℹ️
Two ports in development mode

When started with npm start, the frontend dev server runs on port 3000 and the backend API on port 3001. The dev server automatically proxies /api requests to the backend — you only ever open port 3000 in your browser.

First Launch — Setting Up Your Station

When you open OpenHamClock for the first time you will see the Settings panel asking for your station information. This takes about 30 seconds to complete.

⚙️ Screenshot: First-launch Settings panel assets/img/screenshots/first-launch-settings.png
The Settings panel on first launch. Enter your callsign, grid square, and preferred units. All fields can be changed later from the ⚙️ icon in the top toolbar.

Required fields

Callsign Your amateur radio callsign (e.g. K0CJH, G4ABC, JA1ZZZ). Used for sunrise/sunset times, DXCC entity lookup, and map centering.
Grid Square Your Maidenhead locator, 4 or 6 characters (e.g. IO91 or IO91wm). Determines your map position and great-circle path calculations. OpenHamClock can also calculate your coordinates automatically from a 6-character grid.

Optional but recommended

Units Imperial (miles, °F) or metric (km, °C). Affects distances, temperatures, and wind speed.
Time format 12-hour or 24-hour clock display throughout the dashboard.
Theme Dark (default), Light, Legacy (green-on-black), Retro, or Custom.

What's Next?

You are up and running. Here are the most useful next steps: