Build from Source

You need Go 1.23 or newer. The program is one binary and its only dependency is a YAML parser, so the build takes a few seconds and needs no network access beyond the first download.

Then either run it straight away:

or install it somewhere on your PATH:

Docker

Pull the official image from GitHub Container Registry.

Run the container. It reads /etc/haribon/haribon-config.yml unless you point it somewhere else with HARIBON_CONFIG:

The image ships a default config, so it will also start without the volume mount — it just has nothing useful to send traffic to.

Docker Compose (Full Observability Stack)

Start Haribon with Loki, Promtail, and Grafana in one command. See Usage for how to wire the log exporter to Loki.

Haribon listens on 4444, three sample backends on 4441-4443, Grafana on 3000, and Loki on 3100. The compose file expects data/haribon-config.yml to exist under samples/docker-compose/; copy examples/haribon-config.yml.example there first.

Check It Works

Ask Haribon to read your config and report problems before it starts serving anything. The command exits 0 when the file is fine and 1 when it is not, so it is safe to put in a pipeline.

haribon check reads the settings and reports anything contradictory. haribon validate goes further and checks the file against the JSON schema in schema/haribon-config.schema.json, which catches typos in key names. Use check for a quick answer and validate in CI.

Once it is running, these two endpoints tell you what is going on:

/healthz says the process is up. /readyz says it has at least one backend it considers usable, and returns 503 when it does not.