Server setup

This page sets up fleetd-server on a Linux host with systemd, PostgreSQL and an HTTPS reverse proxy.

1. Create the release key

Agents only install builds signed with your release key. Create it on your own computer, once:

go run ./server/cmd/fleetd-release keygen -key release.key

It prints release_key: …, the public half; you will put it into the server config. Keep release.key offline and backed up. Never copy it to the server: whoever holds it can push agent builds to every machine.

2. Build

VERSION=0.1.0 deploy/build.sh

You need Go and Node.js. The script builds the admin page and static Linux binaries for amd64 and arm64 into bin/, and, because release.key is present, signed agent bundles bin/fleetd-agent-0.1.0-<arch>.release. Set ARCHES=amd64 to build one architecture.

3. Database

Create a role and a database, for example:

CREATE ROLE fleetd LOGIN PASSWORD 'change-me';
CREATE DATABASE fleetd OWNER fleetd;

The server creates and upgrades its tables on every start.

4. Install the server

install -m 755 bin/fleetd-server-amd64 /usr/local/bin/fleetd-server
useradd -r -s /usr/sbin/nologin fleetd
mkdir -p /etc/fleetd
cp deploy/server.example.yaml /etc/fleetd/server.yaml

Edit /etc/fleetd/server.yaml: set database, paste the release_key, and see the configuration reference for everything else. Then:

fleetd-server -config /etc/fleetd/server.yaml keygen        # creates the server key
chown -R root:fleetd /etc/fleetd
chmod 640 /etc/fleetd/server.yaml /etc/fleetd/server.key
fleetd-server -config /etc/fleetd/server.yaml admin-add -totp admin
cp deploy/fleetd-server.service /etc/systemd/system/
systemctl enable --now fleetd-server

The server listens on 127.0.0.1:8480 by default.

5. HTTPS reverse proxy

Agents and the admin page share one address. The proxy must forward WebSockets and keep them open for a long time. Set trust_loopback_proxy: true in the server config so fleetd uses the client address and protocol from the proxy.

server {
    listen 443 ssl;
    http2 on;
    server_name fleetd.example.com;
    ssl_certificate     /etc/letsencrypt/live/fleetd.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/fleetd.example.com/privkey.pem;
    client_max_body_size 128m;   # agent release uploads

    location / {
        proxy_pass http://127.0.0.1:8480;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

fleetd.example.com {
    reverse_proxy 127.0.0.1:8480
}

6. Upload agent builds

Sign in at https://fleetd.example.com, open Settings → Agent releases and upload the .release files from bin/. The one-line installer downloads the newest build for each architecture from here.

7. Create your signing key

In Settings → Signing keys, click Create a signing key in this browser. The private key stays in this browser; the public key is registered with the server and written into every agent installed afterwards.

Now add machines.

Agents on a private network

If some machines share a VPN with the server (WireGuard, Tailscale, …), they can connect over it instead of the public address. Add the VPN address to listen and set internal_agent_url:

listen: ["127.0.0.1:8480", "10.0.0.1:8480"]
internal_agent_url: ws://10.0.0.1:8480/agent/ws

The install command in the admin page then offers Use private network. Plain ws:// is fine here: agent traffic is encrypted and authenticated by Noise either way.

Running with Docker

The repository's docker-compose.yml runs the server and PostgreSQL. For production, edit deploy/docker/server.yaml (database password, release_key) and put an HTTPS proxy in front of port 8480. Inside Docker the proxy does not connect from loopback, so leave trust_loopback_proxy: false.