Skip to content

Docker ​

The image ghcr.io/karanjot786/trail is built for linux/amd64 and linux/arm64. It holds one static binary on a distroless base, runs as a non-root user (uid 65532), keeps its database in /data, and has a health check.

TagWhat it is
latestThe newest release
0.3, 0.3.1A release line, or one exact release
edgeThe main branch, rebuilt on every push

One command ​

sh
docker run -d --name trail --restart unless-stopped \
  -p 8080:8080 -v trail-data:/data \
  ghcr.io/karanjot786/trail

The first start prints a generated dashboard password:

sh
docker logs trail 2>&1 | grep 'Log in'

Open http://<server>:8080 and log in. To choose the password yourself, add -e TRAIL_PASSWORD=.... Other settings are environment variables too, such as -e TRAIL_TZ=Europe/Berlin or -e TRAIL_SITES=mysite=example.com; see Configuration.

The image sets TRAIL_DB=/data/trail.db and TRAIL_ADDR=:8080. Use a named volume as above: it takes the ownership of the image's /data, so the non-root user can write there. For a bind mount, run sudo chown 65532:65532 /path/on/host first.

docker ps shows healthy once the server answers /healthz. You can check it by hand with docker exec trail /trail health.

Plain HTTP is fine for a trial. For real sites, serve Trail over HTTPS: use Compose below, or publish the port on 127.0.0.1 only (-p 127.0.0.1:8080:8080) and put your own proxy in front (see HTTPS).

Docker Compose with automatic HTTPS ​

deploy/compose.yaml runs Trail behind Caddy, which gets and renews a Let's Encrypt certificate by itself. Point the domain's DNS at the server and open ports 80 and 443, then:

sh
curl -fsSLO https://raw.githubusercontent.com/karanjot786/trail/main/deploy/compose.yaml
echo "DOMAIN=stats.example.com" > .env && docker compose up -d

Read the password with docker compose logs trail | grep 'Log in' and open https://stats.example.com.

Settings can live in a .env file next to compose.yaml, so later docker compose commands pick them up:

sh
DOMAIN=stats.example.com
TRAIL_PASSWORD=choose-a-long-one   # optional
TRAIL_TZ=Europe/Berlin             # optional, default UTC
TRAIL_SITES=blog=example.com       # optional

Trail's port is not published. Only Caddy reaches it, over the private Compose network, so the visitor IP that Caddy forwards is trusted with the default TRAIL_TRUSTED_PROXIES. The data is in the trail_trail-data volume.

To test the stack on your own machine, use DOMAIN=localhost: Caddy then serves a certificate from its own local authority, which your browser will warn about. HTTP_PORT and HTTPS_PORT move it off ports 80 and 443.

HTTPS with your own proxy ​

Put Trail behind any reverse proxy that terminates TLS, such as Caddy, nginx or your platform's load balancer. The dashboard cookie is marked Secure when the request arrives over TLS or with X-Forwarded-Proto: https.

Trail believes X-Forwarded-For only from a trusted proxy. By default that is loopback and private addresses, which covers a proxy on the same host or Docker network, plus Cloudflare. A client that connects to port 8080 directly cannot fake its IP, but it can skip the proxy, so publish the port on 127.0.0.1 only. Other setups are in Client IP and proxies.

Build the image yourself ​

sh
git clone https://github.com/karanjot786/trail && cd trail
docker build -t trail .
docker run -d --name trail -p 8080:8080 -v trail-data:/data trail

The Dockerfile builds the tracker and the dashboard with Node, cross-compiles the Go binary for the target platform, and copies it into the distroless image. docker buildx build --platform linux/amd64,linux/arm64 . builds both architectures without emulation.

Geo data ​

Countries work with no setup: the image carries the built-in DB-IP Lite Country database. For region and city, mount a DB-IP Lite City file and point TRAIL_GEO_DB at it. See Geo database.

sh
docker run ... -v /srv/geo:/geo:ro -e TRAIL_GEO_DB=/geo/dbip-city-lite.mmdb ghcr.io/karanjot786/trail

Next ​