Install¶
Requirements¶
- Linux with Docker and the Compose plugin.
- A host address where the DNS can bind port 53. Binding
0.0.0.0:53conflicts withsystemd-resolvedon 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)¶
- Management host: write
~/gslb-ha/api.env(mode 600) withGSLB_API_USER,GSLB_API_PASSWORD,GSLB_API_TOKENandGSLB_WEB_PORT(optionallyGSLB_API_RO_TOKEN, a credential that reads everything and writes nothing, for a dashboard or a monitoring probe, and theGSLB_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
- Each DNS host: write
~/gslb-ha/dns.envwithGSLB_API_URL(http://<management-host>:8088),GSLB_API_TOKEN, a uniqueGSLB_INSTANCE, andGSLB_ADDR(the node's LAN address). For a VIP, setGSLB_ADDR=<node>,<vip>andGSLB_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
- 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.