Linux service

This guide runs one native server as an unprivileged systemd service.

• Build with Go 1.27.3 and use an external PostgreSQL database.
• The embedded UI is committed; Node is needed only when rebuilding it.

Build and install

• The commands below start from a source checkout.
  • When using a reviewed native release archive instead, use its nines-server binary in the install command in place of nines-server-linux-amd64; no Go compiler or source build is needed.
  • Match the archive to the host operating system and architecture and verify its checksums first.

make build

When building on macOS for Linux, select the deployment architecture explicitly:

mkdir -p dist
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o dist/nines-server-linux-amd64 ./cmd/server

• Use arm64 for an ARM host.
  • Transfer the matching binary over your normal verified delivery channel.
  • On the Linux host, create the service account and directories, then install the binary:

sudo useradd --system --home-dir /var/lib/nines --shell /usr/sbin/nologin nines
sudo install -d -o root -g root -m 0755 /opt/nines
sudo install -d -o root -g nines -m 0750 /etc/nines
sudo install -o root -g root -m 0755 ./nines-server-linux-amd64 /opt/nines/nines-server
sudo install -m 0644 deploy/systemd/nines.service /etc/systemd/system/nines.service

• useradd is a one-time step; adapt it if the account already exists or your distribution uses a different nologin path.
  • The service manager creates /var/lib/nines and /run/nines for the service.
  • Keep TLS root CAs installed for PostgreSQL, providers and identity clients.

Runtime configuration

Create /etc/nines/nines.env, owned by root with mode 0600:

DATABASE_URL=postgres://nines:URL_ENCODED_PASSWORD@db.internal:5432/nines?sslmode=verify-full
API_TOKEN=REPLACE_WITH_A_RANDOM_VALUE_OF_AT_LEAST_24_CHARACTERS
# Optional server-owned configuration:
# TENANTS_FILE=/etc/nines/tenants.yaml
# AUTH_CONFIG_FILE=/etc/nines/auth.yaml
# NINES_PUBLIC_URL=https://nines.example.com
# NINES_BOOTSTRAP_PASSWORD=GENERATE_A_RANDOM_PASSWORD_FOR_LOCAL_ACCOUNTS
# NINES_ENTRA_CLIENT_SECRET=...

• Use a secret manager or a protected editor to set real values. Environment files contain secrets.
  • The native process does not load a checkout's .env automatically.
  • Add a sslrootcert connection parameter if PostgreSQL uses a private CA, and make the CA readable to the service.
• For tenant or identity files, use root ownership, group nines and mode 0640. Resolve secret fields through the environment variables named by each YAML file. See team login.

sudo systemctl daemon-reload
sudo systemctl enable --now nines
sudo systemctl status nines
sudo journalctl -u nines --since '10 minutes ago'
curl --fail http://127.0.0.1:8080/healthz

• The service writes structured logs to stdout/journald.
  • Standard OTEL_* environment variables configure optional telemetry exports.
  • No Prometheus /metrics endpoint is advertised by this guide.

HTTPS

Terminate TLS at a trusted reverse proxy while leaving Nines on loopback. For example, an operator-managed Caddy configuration is:

slo.example.com {
    reverse_proxy 127.0.0.1:8080
}

• Replace the hostname, configure DNS and certificate issuance, and follow your proxy's deployment policy.
  • For a network-separated proxy, protect the private hop and restrict direct access to Nines.
  • An identity publicURL must be the external HTTPS origin.
  • Nines constructs OIDC callbacks from that configured origin, not an arbitrary request host.
• The reverse proxy must allow normal API methods, request bodies and streamed responses.
  • Choose timeouts appropriate for the bounded workflow/replay features you enable.
  • Do not add public caching to authenticated API responses.

Upgrade

• Back up the database and configuration first.
  • Stop the service, install the reviewed binary, start it and verify both API access and provider collection.
  • Do not run old and new collecting servers simultaneously. See backup and restore.
• Reference: Caddy's reverse proxy quickstart.