Configuration‐Reference

Configuration Reference

All settings go in the .env file in your OpenHamClock root directory. Restart the server after changes.

Most settings can also be changed through the browser Settings panel without editing .env.

Station (Required)

Variable	Default	Description
CALLSIGN	N0CALL	Your amateur radio callsign
LOCATOR	FN31	Maidenhead grid locator (4 or 6 character)
LATITUDE	(from grid)	Station latitude (calculated from LOCATOR if not set)
LONGITUDE	(from grid)	Station longitude (calculated from LOCATOR if not set)

Server

Variable	Default	Description
PORT	3001	Backend API server port (dev). Production uses 3000
HOST	localhost	Bind address. Set to 0.0.0.0 for LAN/cloud access
API_WRITE_KEY	(empty)	Auth key for POST endpoints. Required for cloud deployments
CORS_ORIGINS	(reflect)	Comma-separated allowed origins for CORS
LOG_LEVEL	warn	Logging: debug, info, warn, error

Display Preferences

Variable	Default	Description
UNITS	imperial	Legacy: imperial or metric
DISTUNITS	imperial	Distance units
TEMPUNITS	imperial	Temperature units
PRESSUNITS	imperial	Pressure units
TIME_FORMAT	12	12 or 24 hour
THEME	dark	dark, light, legacy, or retro
LAYOUT	modern	modern, classic, or dockable
TZ	(browser)	IANA timezone (e.g. America/New_York)

Feature Toggles

Variable	Default	Description
SHOW_POTA	true	Show POTA spots panel
SHOW_SATELLITES	true	Show satellite tracking
SHOW_DX_PATHS	true	Show DX cluster paths on map
SHOW_DX_WEATHER	true	Show weather at DX location
CLASSIC_ANALOG_CLOCK	false	Show analog clock in classic layout

DX Cluster

Variable	Default	Description
DX_CLUSTER_SOURCE	auto	auto, proxy, hamqth, dxspider, or set custom in UI
DX_CLUSTER_CALLSIGN	(CALLSIGN-56)	Login callsign for DX cluster
DX_CLUSTER_HOST	(empty)	Custom telnet host (when source=custom)
DX_CLUSTER_PORT	7300	Custom telnet port
SPOT_RETENTION_MINUTES	30	How long to keep DX spots
DXSPIDER_PROXY_URL	(built-in)	Custom DX Spider proxy URL

See DX Cluster Setup for detailed configuration.

WSJT-X

Variable	Default	Description
WSJTX_ENABLED	true	Enable WSJT-X UDP listener
WSJTX_UDP_PORT	2237	UDP port for WSJT-X data
WSJTX_RELAY_KEY	(empty)	Auth key for remote relay agent

See WSJT-X Integration for setup details.

N1MM+ / Contest Logging

Variable	Default	Description
N1MM_UDP_ENABLED	false	Enable N1MM UDP listener
N1MM_UDP_PORT	12060	UDP port (must match N1MM config)
N1MM_MAX_QSOS	200	Max QSOs in memory
N1MM_QSO_MAX_AGE_MINUTES	360	QSO retention (6 hours)

See N1MM Integration for full setup guide.

APRS-IS

Variable	Default	Description
APRS_ENABLED	false	Enable APRS-IS connection
APRS_HOST	rotate.aprs2.net	APRS-IS server
APRS_PORT	14580	APRS-IS port
APRS_FILTER	(empty)	Server-side filter (e.g. r/40/-75/500)
APRS_MAX_AGE_MINUTES	60	Station cache retention

Rotator Control

Variable	Default	Description
ROTATOR_PROVIDER	none	pstrotator_udp or none
PSTROTATOR_HOST	192.168.1.43	PstRotatorAz IP address
PSTROTATOR_UDP_PORT	12000	PstRotatorAz UDP port
ROTATOR_STALE_MS	5000	Stale reading timeout

N3FJP

Variable	Default	Description
N3FJP_QSO_RETENTION_MINUTES	1440	QSO cache retention (24 hours)

Ambient Weather

Variable	Default	Description
VITE_AMBIENT_APPLICATION_KEY	(empty)	AmbientWeather.net application key
VITE_AMBIENT_API_KEY	(empty)	AmbientWeather.net API key
VITE_AMBIENT_DEVICE_MAC	(auto)	Specific weather station MAC
VITE_AMBIENT_POLL_SECONDS	30	Polling interval (min 15)

External Services

Variable	Default	Description
ITURHFPROP_URL	(public service)	ITU-R P.533-14 prediction service URL
OPENWEATHER_API_KEY	(empty)	Only for Cloud Layer map overlay
QRZ_USERNAME	(empty)	QRZ.com XML API (improves callsign accuracy)
QRZ_PASSWORD	(empty)	QRZ.com password

Auto Update

Variable	Default	Description
AUTO_UPDATE_ENABLED	false	Enable periodic git-based updates
AUTO_UPDATE_INTERVAL_MINUTES	60	Check interval
AUTO_UPDATE_ON_START	false	Check on server startup
AUTO_UPDATE_EXIT_AFTER	true	Exit after update (for systemd restart)

Settings Sync

Variable	Default	Description
SETTINGS_SYNC	false	Sync UI settings to server (for Pi/single-operator)
SETTINGS_FILE	(auto)	Custom path for settings file

Security

Variable	Default	Description
API_WRITE_KEY	(empty)	Required for cloud deployments. Protects POST endpoints
CORS_ORIGINS	(reflect)	Restrict which origins can call your API

Configuration Priority

Settings are resolved in this order (first match wins):

1. Environment variables (.env or system)
2. config.json (user preferences file)
3. Built-in defaults