Skip to content

Install

Requirements

  • Linux with Docker and the Compose plugin.
  • A host address where the DNS can bind port 53. Binding 0.0.0.0:53 conflicts with systemd-resolved on most distributions; bind the host's LAN address instead (GSLB_ADDR=192.0.2.10).
  • A directory for the YAML (single host) or a management host (fleet).

Single host

git clone <repository> gslb && cd gslb
printf 'GSLB_API_USER=admin\nGSLB_API_PASSWORD=change-me\n' > .env
GSLB_ADDR=192.0.2.10 docker compose --env-file .env -f docker-compose.lot2.yml up -d

Open http://<host>:8080 (override with GSLB_WEB_PORT). On a fresh install the console shows the first-start wizard: zone, TTL, one pool, its backends and the operator password. The first save is applied through the same validate → write → acknowledge → roll back path as every later one.

The compose files already declare every variable the containers read, as pass-throughs. To turn on single sign-on, a proxy header or a longer retention, add the lines to .env and restart: never edit the compose file. An empty value leaves the feature off — see Configuration § Environment.

The images are tagged <name>:${GSLB_VERSION:-local}: a clone with no variable builds gslb:local, gslb-api:local, gslb-web:local; put GSLB_VERSION=0.10.6 in the env file to run a published release instead of building.

The composes:

File What it starts
docker-compose.lot2.yml DNS + API + web on one host, sharing /state
docker-compose.ha-api.yml API + web on the management host
docker-compose.ha-dns.yml one DNS node, run on every DNS host
docker-compose.ha-vip.yml optional keepalived overlay for the DNS node

Fleet (HA)

  1. Management host: write ~/gslb-ha/api.env (mode 600) with GSLB_API_USER, GSLB_API_PASSWORD, GSLB_API_TOKEN and GSLB_WEB_PORT (optionally GSLB_API_RO_TOKEN, a credential that reads everything and writes nothing, for a dashboard or a monitoring probe, and the GSLB_OIDC_* / GSLB_SESSION_* block of OIDC — every one is already declared in the compose), then:

sh docker compose -p gslb-ha --env-file ~/gslb-ha/api.env \ -f docker-compose.ha-api.yml up -d

  1. Each DNS host: write ~/gslb-ha/dns.env with GSLB_API_URL (http://<management-host>:8088), GSLB_API_TOKEN, a unique GSLB_INSTANCE, and GSLB_ADDR (the node's LAN address). For a VIP, set GSLB_ADDR=<node>,<vip> and GSLB_HEALTHCHECK_ADDR=<node>, then add the optional -f docker-compose.ha-vip.yml (see High availability):

sh docker compose -p gslb-dns1 --env-file ~/gslb-ha/dns.env \ -f docker-compose.ha-dns.yml up -d

  1. Open the console: the Instances page lists every node that pushed a snapshot. See High availability for the VIP and the failure cases.

Environment

The complete list, with defaults, is in Configuration § Environment. A single host needs three of them: GSLB_ADDR (the address to bind) and GSLB_API_USER / GSLB_API_PASSWORD for the console. YAML wins for topology (pools, rules, health settings); the environment wins for port, address, log level and retention.

Upgrading

The console ships in English and French. The language defaults to the browser's; the choice (Auto, English, Français) is in Settings → Appearance → Language and is remembered in that browser.

The API applies its SQLite migrations at startup: a lot 2 database is adopted without losing a row. Back up the /data volume first. The DNS image is stateless in HA mode and re-pulls its configuration at every start.