Skip to content

Binary, systemd and Caddy ​

Trail compiles to a single static file (CGO_ENABLED=0) with the tracker and the dashboard embedded. Copy it to any Linux server and run it.

Install script ​

sh
curl -fsSL https://raw.githubusercontent.com/karanjot786/trail/main/install.sh | sh

The script:

  1. downloads trail_<os>_<cpu>.tar.gz from the latest GitHub release (Linux, macOS and FreeBSD; amd64 and arm64);
  2. checks it against the release's checksums.txt and stops on a mismatch;
  3. installs /usr/local/bin/trail;
  4. on Linux with systemd: creates a trail system user, /var/lib/trail, /etc/trail.env (mode 600, listening on 127.0.0.1:8080) and the hardened trail.service shown below, starts it and prints the generated dashboard password.

Running it again updates the binary and restarts the service. It never touches an existing /etc/trail.env or the database.

VariableEffect
TRAIL_VERSION=v0.3.1Install that release instead of the latest
TRAIL_ADDR=:8080Listen address for a new /etc/trail.env (default 127.0.0.1:8080)
TRAIL_INSTALL_DIR=$HOME/.local/binPut the binary elsewhere
TRAIL_NO_SERVICE=1Install the binary only

Pass them to sh, e.g. curl -fsSL .../install.sh | TRAIL_NO_SERVICE=1 sh. To read the script first, download it, look, then run sh install.sh. Or do it by hand: download the archive and checksums.txt from the release page, run sha256sum -c --ignore-missing checksums.txt, and unpack trail.

Then add HTTPS with Caddy.

Build from source ​

On your machine, with Go 1.26+, Node 22+ and pnpm:

sh
git clone https://github.com/karanjot786/trail && cd trail
make build                                   # tracker, dashboard, then ./trail
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
  go build -trimpath -ldflags="-s -w" -o trail-linux ./cmd/trail
scp trail-linux server:/usr/local/bin/trail

make build must run first so the dashboard and tracker files exist to be embedded. The cross-compile line reuses them.

systemd ​

Create a user and a data directory:

sh
sudo useradd --system --home /var/lib/trail --create-home trail

Put the settings in an environment file readable only by root. TRAIL_PASSWORD and TRAIL_SECRET are optional: without them the first start logs a generated password (journalctl -u trail | grep 'Log in') and keeps the session key in the database.

ini
TRAIL_PASSWORD=change-me
TRAIL_SITES=mysite=example.com
TRAIL_DB=/var/lib/trail/trail.db
TRAIL_ADDR=127.0.0.1:8080
TRAIL_TZ=Europe/Berlin
ini
[Unit]
Description=Trail analytics
After=network-online.target
Wants=network-online.target

[Service]
User=trail
EnvironmentFile=/etc/trail.env
ExecStart=/usr/local/bin/trail serve
Restart=on-failure
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/trail
PrivateTmp=true

[Install]
WantedBy=multi-user.target
sh
sudo chmod 600 /etc/trail.env
sudo systemctl daemon-reload
sudo systemctl enable --now trail
journalctl -u trail -f

Trail stops cleanly on SIGTERM: it finishes in-flight requests and flushes queued events before closing the database.

Caddy ​

Binding to 127.0.0.1 keeps Trail private; Caddy serves it over HTTPS and sets X-Forwarded-For and X-Forwarded-Proto for you. Trail trusts that header because Caddy connects from loopback (see Client IP and proxies).

txt
stats.example.com {
	encode zstd gzip
	reverse_proxy 127.0.0.1:8080
}
sh
sudo systemctl reload caddy

Then add the /_t/* rewrite on the sites you track, so the tracker loads from their own domain. See Rewrites.

Next ​