Quick start

1. Run the server

The fastest path is Docker. One container, one volume, no database.

docker run -d --name trckable \
  -p 8080:8080 \
  -v trckable-data:/data \
  -e TRCKABLE_BASE_URL=https://stats.example.com \
  ghcr.io/trckable/trckable:latest

On the first start it prints a setup URL with a one-time token:

trckable is not set up yet — open this link to create your account
  url=https://stats.example.com/setup#token=tkb_setup_...

That link works exactly once. Open it, pick an email and a password, and you have an owner account.

Other ways to run it (any host, from source, systemd, behind a reverse proxy) are in Self-hosting.

2. Add your site

In the dashboard, Add site and type the domain. You get a site id and an install snippet.

3. Put the script on the page

<script
  defer
  data-site="tkb_a1b2c3d4"
  data-domain="example.com"
  src="https://stats.example.com/js/tkb_a1b2c3d4.js">
</script>

That URL is your site's own script: it carries the features that site's modules turn on, and nothing else.

If your site is a React or Next.js app, the npm package is the more accurate install, because the tracker is bundled into your own code and nothing to block is ever requested:

npm i trckable

import { Analytics } from 'trckable/react'
<Analytics site="tkb_a1b2c3d4" host="https://stats.example.com" />

Both are covered properly in Install.

4. Check it

The dashboard shows an install card, waiting for the first visit, until it has seen one. Open your site in another tab; the card says when the visit arrives. After that, Settings → Verify checks from the outside that the snippet is on your homepage.

From a terminal:

npx trckable doctor https://example.com

doctor looks at your site from the outside: whether it is served over HTTPS, and whether the events endpoint answers a browser's cross-origin check.

5. Decide about cookies

This is the one decision worth making on day one, because it changes what the script stores.

• Cookieless mode — nothing is stored in the browser at all. In countries with an analytics exemption (France, Italy, the Netherlands, Spain, the UK) that can let you skip the banner; Germany and Austria still ask for consent. New-versus-returning is only right within a day. More
• A cookie, and ask first — either trckable's own cookie bar, or the consent manager you already run, which trckable reads. A visitor who declines is not counted at all.
• A cookie, no asking — fine in some places, not in others. trckable will not pretend otherwise.

Settings → Data & privacy, and the page writes the privacy paragraph for whichever you pick.

Next

• Goals — count signups, not just pageviews
• Revenue — see which traffic pays
• Backups — before you have data worth losing