Skip to content

Quickstart ​

You need Docker, or Go 1.26+ with Node 22+ and pnpm to build from source. It takes about two minutes. For a server with HTTPS, see Self-hosting.

Start the server ​

sh
docker run -d --name trail -p 8080:8080 -v trail-data:/data \
  -e TRAIL_PASSWORD=change-me \
  -e TRAIL_SITES=mysite=localhost \
  ghcr.io/karanjot786/trail
sh
git clone https://github.com/karanjot786/trail && cd trail
make build
TRAIL_PASSWORD=change-me TRAIL_SITES=mysite=localhost ./trail

The log ends with trail listening on :8080 (sites: 1, api tokens: 0). TRAIL_SITES is optional. It adds a site id (mysite) with its domain at startup. You can also add sites in the dashboard (step 3). Events for ids that do not exist are rejected.

Add the script to a page ​

Any page on any port works. data-dev is needed only because the page runs on localhost, where the tracker stays quiet unless told otherwise.

html
<script defer src="http://localhost:8080/_t/t.js" data-site="mysite"
  data-api="http://localhost:8080/_t/e" data-dev></script>

On a real site you proxy /_t/* through your own domain, and the tag shrinks to <script defer src="/_t/t.js" data-site="mysite"></script>. See Rewrites.

Open the dashboard ​

Go to http://localhost:8080, sign in with TRAIL_PASSWORD, and open your page in another tab. The header shows 1 online within a few seconds.

If the server has no sites yet, or your site has not received an event, the dashboard walks you through setup: add your website, install the script, and watch for the first visit. See First run in the dashboard.

To track another site, open the site switcher and choose Add a website. You get the same steps, with the snippet for a script tag, Next.js, Astro or npm, and "Receiving data" once the first event arrives.

TIP

Events from localhost are tagged with the development environment. The dashboard shows production by default, so pick All Environments in the header to see test pageviews in the charts. The online count covers every environment.

INFO

Trail only accepts events from the site's own domain, its subdomains, hosts you list as allowed origins, and localhost. Anything else gets a 403. See Allowed origins.

Next ​