Installation

This guide explains how to install and run Nexus GSLB (gslbd) on Linux using:

The automated install script.
Docker / Docker Compose.
A manual tarball install from pre-built binaries for Linux, available at gslb.nexus/releases.

For Kubernetes deployments see docs/user/Kubernetes.md.

Supported platforms

OS	Architectures
Linux	x86_64 (amd64), arm64
macOS	x86_64 (amd64), Apple Silicon (arm64)
Windows	x86_64 (amd64)

Directory layout (Linux / systemd)

Path	Purpose
`/usr/local/bin/gslbd`	Daemon binary
`/usr/local/bin/gslbctl`	Management CLI
`/etc/gslb/config.yaml`	Main configuration
`/etc/gslb/gslbd.env`	License credentials (env overrides)
`/var/lib/gslbd/gslbd.db`	SQLite state database

Option A: Automated install script (Linux, systemd)

The fastest path for bare-metal Linux. Requires root.

curl -fsSL https://gslb.nexus/install.sh | sudo bash

The script auto-detects your CPU architecture (amd64 or arm64), downloads the latest signed archive from gslb.nexus/releases, verifies the SHA256 checksum, installs the binaries, creates a hardened gslbd system user, and enables the systemd unit.

After install:

# 1. Edit configurationsudo nano /etc/gslb/config.yaml# 2. Set license key (free tier works without one)sudo nano /etc/gslb/gslbd.env# Add: GSLB_LICENSE_KEY=<key-from-gslb.nexus># 3. Startsudo systemctl start gslbdsudo systemctl status gslbdjournalctl -u gslbd -f# 4. Health checkcurl http://localhost:8080/api/v1/health

Upgrade

Re-run the install script — it backs up the previous binaries to *.bak automatically:

curl -fsSL https://gslb.nexus/install.sh | sudo bashsudo systemctl restart gslbd

To pin a version:

NEXUS_VERSION=v0.1.0 curl -fsSL https://gslb.nexus/install.sh | sudo bash

Rollback

sudo cp /usr/local/bin/gslbd.bak   /usr/local/bin/gslbdsudo cp /usr/local/bin/gslbctl.bak /usr/local/bin/gslbctlsudo systemctl restart gslbd

Port 53

The default DNS port is 5353 and requires no special privileges. To bind to port 53:

In /etc/gslb/config.yaml set dns.port: 53

In /etc/systemd/system/gslbd.service uncomment:

AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

sudo systemctl daemon-reload && sudo systemctl restart gslbd

Option B: Docker Compose

The recommended container deployment. Runs gslbd, the Next.js WebUI, and Caddy (automatic HTTPS) as a single Compose stack.

Prerequisites: Docker 24+ with the Compose plugin, ports 53, 80, and 443 available.

# 1. Download the release Compose file and example configcurl -fsSLO https://gslb.nexus/releases/latest/docker-compose.release.ymlcurl -fsSLO https://gslb.nexus/releases/latest/config.yaml.examplemv config.yaml.example config.yaml# 2. Edit config.yaml — set your domain, NS names, and pool endpoints#    Minimum required fields:#      dns.domain, dns.nsNames, loadBalancer.endpointsnano config.yaml# 3. Also edit the Caddyfile to set your domaincurl -fsSLO https://gslb.nexus/releases/latest/Caddyfilenano Caddyfile   # replace "example.com" with your domain# 4. Start the stackdocker compose -f docker-compose.release.yml up -d# 5. Create the first admin usercurl -X POST http://localhost:8080/api/v1/auth/setup \  -H 'Content-Type: application/json' \  -d '{"username":"admin","password":"your-secure-password"}'# 6. Open the WebUIopen https://your.domain

Port mapping

Host port	Purpose
53/udp + 53/tcp	DNS
80/tcp	HTTP (Caddy ACME + redirects)
443/tcp	HTTPS (WebUI + API via Caddy)

The SQLite database is persisted in a named Docker volume (gslbd-data).

Set a license key

GSLB_LICENSE_KEY=your-key docker compose -f docker-compose.release.yml up -d# or add to a .env file:echo "GSLB_LICENSE_KEY=your-key" >> .env

Upgrade

docker compose -f docker-compose.release.yml pulldocker compose -f docker-compose.release.yml up -d

Run with Podman

podman compose -f docker-compose.release.yml up -d

Option C: Manual tarball install

Download the archive for your platform from gslb.nexus/releases, verify the checksum, and install manually.

# Example: Linux amd64VERSION=0.1.0ARCHIVE="nexus-gslb-${VERSION}-linux-amd64.tar.gz"curl -fsSLO "https://gslb.nexus/releases/v${VERSION}/${ARCHIVE}"curl -fsSLO "https://gslb.nexus/releases/v${VERSION}/nexus-gslb-${VERSION}-checksums.txt"# Verifygrep "$ARCHIVE" "nexus-gslb-${VERSION}-checksums.txt" | sha256sum -c -# Extracttar -xzf "$ARCHIVE"cd "nexus-gslb-${VERSION}-linux-amd64"# Install binariessudo install -m 755 gslbd   /usr/local/bin/gslbdsudo install -m 755 gslbctl /usr/local/bin/gslbctl# Install config and systemd unitsudo mkdir -p /etc/gslb /var/lib/gslbdsudo install -m 640 deploy/config.yaml.example /etc/gslb/config.yamlsudo install -m 644 deploy/gslbd.service /etc/systemd/system/gslbd.servicesudo systemctl daemon-reloadsudo systemctl enable gslbd# Edit, then startsudo nano /etc/gslb/config.yamlsudo systemctl start gslbd

Available archive names:

Platform	Archive
Linux amd64	`nexus-gslb-VERSION-linux-amd64.tar.gz`
Linux arm64	`nexus-gslb-VERSION-linux-arm64.tar.gz`
macOS amd64	`nexus-gslb-VERSION-darwin-amd64.tar.gz`
macOS arm64	`nexus-gslb-VERSION-darwin-arm64.tar.gz`
Windows amd64	`nexus-gslb-VERSION-windows-amd64.zip`

DEB and RPM packages are also available for Linux:

# Debian / Ubuntusudo apt install ./nexus-gslb_${VERSION}_linux_amd64.deb# RHEL / Fedora / Rockysudo rpm -i nexus-gslb-${VERSION}-1.amd64.rpm

Management CLI (gslbctl)

gslbctl manages all resources over the REST API. Configure it with environment variables:

export GSLB_SERVER_URL=https://your.domainexport GSLB_API_KEY=your-api-keygslbctl pools listgslbctl services listgslbctl cluster status

Generate an API key in the WebUI under Settings → API Tokens, or via:

gslbctl users apikey create --name automation

Run gslbctl help for the full command list.

Uninstall

sudo systemctl disable --now gslbd || truesudo rm -f /etc/systemd/system/gslbd.servicesudo systemctl daemon-reloadsudo rm -f /usr/local/bin/gslbd /usr/local/bin/gslbctlsudo rm -rf /etc/gslb /var/lib/gslbd

Optional: Apply a license key

Free tier installs are rate-limited. To unlock paid features, obtain a license from gslb.nexus and apply it:

# Preferred: set as environment variable (never stored in config file)echo "GSLB_LICENSE_KEY=your-key" | sudo tee -a /etc/gslb/gslbd.envsudo systemctl restart gslbd

Or apply at runtime via the WebUI: Admin → License → Apply Key.

Optional: Enable DNSSEC (paid)

# /etc/gslb/config.yaml
dnssec:
  enabled: true
  zone: "gslb.example.com."
  ksk:
    pemFile: "/etc/gslb/ksk.pem"
  zsk:
    pemFile: "/etc/gslb/zsk.pem"
    signatureValidityDays: 7

See docs/reference/DNSSEC.md for key generation and DS record submission.

Optional: Enable NATS clustering (paid)

# /etc/gslb/config.yaml
cluster:
  id: "prod-cluster"
  state:
    nats:
      servers:
        - "nats://nats-1.internal:4222"
        - "nats://nats-2.internal:4222"
        - "nats://nats-3.internal:4222"

See docs/user/ThreeNodeCluster-BareMetal.md for a full three-node setup walkthrough.