Litemetrics Quickstart - Self-hosted analytics in 5 minutes

Quickstart

Litemetrics has four moving parts: a tracker that runs in your users' browsers, a server that collects events, a database that stores them (ClickHouse, Postgres, or MongoDB), and a React dashboard you embed into your product. This guide gets all four running in about five minutes.

1. Run the collector with Docker

The fastest path is the bundled Docker Compose stack. It starts ClickHouse and the Litemetrics server together, with healthchecks and persistent volumes already wired up.

git clone https://github.com/metehankurucu/litemetrics.git
cd litemetrics
docker compose up -d

The collector listens on http://localhost:3002. ClickHouse is exposed on 8123. To use Postgres instead, see the Postgres setup guide; to use MongoDB, run with the --profile mongodb flag.

Prefer one-click hosting? Deploy the same image to Railway with the Railway template. You will get an HTTPS URL in under a minute.

2. Create a site

Sites are how Litemetrics isolates tenants. Each site has its own public siteId (used by the tracker) and a private secret key (used to read stats). Create one with the admin endpoint:

curl -X POST http://localhost:3002/api/sites \
  -H "X-Litemetrics-Admin-Secret: admin" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "hostnames": ["myapp.com"]}'

The response includes the siteId and secretKey. Save the secretKey in your backend secrets store; it is what the dashboard uses to read stats for that tenant.

3. Add the tracker to your site

The browser tracker is under 3.5KB gzipped, loads asynchronously, and auto-tracks pageviews, sessions, scroll depth, button clicks, and outbound links.

<script src="http://localhost:3002/litemetrics.js" defer></script>
<script>
  Litemetrics.createTracker({
    siteId: 'YOUR_SITE_ID',
    endpoint: 'http://localhost:3002/api/collect',
  });
</script>

Using React or Next.js? See the React integration guide for the idiomatic provider and hooks setup.

4. Verify events are flowing

Open the page in a browser. The tracker fires a pageview on load and a session event on first interaction. Confirm with:

curl "http://localhost:3002/api/stats?siteId=YOUR_SITE_ID&metric=pageviews&period=24h" \
  -H "X-Litemetrics-Site-Secret: YOUR_SECRET_KEY"

You should see a count greater than zero. If not, check that hostnames on the site allows the origin you are testing from, and that the tracker URL points to the right collector.

5. Embed the dashboard in your app

The dashboard is a React component. Drop it into any page in your product, pass the customer's siteId, and they get a full analytics view scoped to their data only.

import {
  LitemetricsProvider,
  AnalyticsDashboard,
} from '@litemetrics/ui';

export function CustomerAnalytics({ customerId }) {
  return (
    <LitemetricsProvider
      baseUrl="https://your-server.com/api"
      siteId={customerId}
      secretKey={getSecretForCustomer(customerId)}
    >
      <AnalyticsDashboard theme="midnight" />
    </LitemetricsProvider>
  );
}

That is it. Each customer sees only their own data, the dashboard respects your theme, and you never had to design a chart.

Where to next