Skip to content

Getting started

Hora is a single self-contained binary: migrations and templates are compiled in, history lives in one SQLite file. The fastest path is the Docker image - a static musl binary on Alpine, about 15 MB.

Terminal window
mkdir -p hora-config && cp config.example.toml hora-config/config.toml
# edit hora-config/config.toml
docker run -d --name hora --restart unless-stopped \
-p 8787:8787 \
-v "$PWD/hora-config:/etc/hora" \
-v hora-data:/data \
ghcr.io/uplg/hora:latest

The status page is at http://localhost:8787/. Put it behind your reverse proxy on whatever domain you like - Hora is self-contained and assumes nothing about who consumes it.

Your history lives on the hora-data volume and survives upgrades.

Mount the config’s directory, as above, not config.toml alone: a file mounted on its own stays the file it was when the container started, so the first editor or deploy tool that replaces it by renaming would leave Hora on the old one until a restart (see Live reload).

[page]
title = "My services"
[server]
bind = "0.0.0.0:8787"
database_path = "/data/hora.db"
[alerts]
fail_threshold = 3 # consecutive failures before "down" - kills flapping
cert_expiry_days = 14 # warn before a TLS certificate expires
[[channels]]
name = "ops"
type = "telegram"
token = "${HORA_TELEGRAM_TOKEN}"
chat_id = "123456"
[[monitors]]
id = "website"
name = "Website"
target = "https://example.com"
interval_secs = 60
timeout_secs = 10

Any ${VAR} in the file is replaced from the environment at load, so secrets stay out of the config: pass -e HORA_TELEGRAM_TOKEN=123:abc to the container. A variable that is not set is warned about, with the key that uses it. Validate with hora check (non-zero exit on error, CI-friendly; --strict also fails on warnings), and verify your notification chain with hora test-alert before the first real incident.

kind = "icmp" monitors use an unprivileged datagram socket, so they need no extra capability as long as the container’s group id is within the kernel’s net.ipv4.ping_group_range - Docker’s default (0 2147483647) already covers the image’s 10001 user, including rootless Docker, and it keeps working with --cap-drop ALL and a read-only root filesystem. If your host narrows that range, either widen it (--sysctl net.ipv4.ping_group_range="0 2147483647") or grant --cap-add NET_RAW; otherwise icmp monitors simply report down with a clear reason.

On Kubernetes the range comes from the node’s default, often 1 0 (nobody): set it on the pod. net.ipv4.ping_group_range is a namespaced, safe sysctl since Kubernetes 1.18, so no kubelet flag is needed:

spec:
securityContext:
runAsUser: 10001
runAsGroup: 10001
sysctls:
- name: net.ipv4.ping_group_range
value: "0 2147483647"
containers:
- name: hora
securityContext:
capabilities: { drop: ["ALL"] }
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
Terminal window
git clone https://github.com/uplg/hora && cd hora
cp config.example.toml config.toml # then edit
cargo run -p hora

Building requires Rust 1.99.1 or later, a C toolchain and cmake (for aws-lc-rs, the rustls crypto provider). The quality gate is just gate (fmt, clippy, cargo-deny, cargo-audit, tests) - the exact checks CI runs.

Four are read directly (everything else lives in the config file):

Variable Meaning
HORA_CONFIG Path to the config file (default ./config.toml)
HORA_DATABASE_PATH Overrides server.database_path
HORA_BIND Overrides server.bind
HORA_EXEC_DIR Enables exec probes and confines them to this directory

Plus HORA_LOG for log filtering (a tracing filter string, default info). Logs are coloured only when standard output is a terminal, and never when NO_COLOR is set.