How to set up self-hosted analytics
A practical map for self-hosting Pug end to end. It covers what to provision and the order to do it in; the exact commands live in the docs and stay current with each release.
What you’ll need
- A server or cluster you control (VM, container platform, or k8s)
- PostgreSQL, ClickHouse, and NATS reachable from the binary
- A TLS-terminating reverse proxy for the public endpoint
Pug is in open beta — features are live and usable while we harden for general availability. Always cross-check versions against the docs.
Self-hosting, in six steps
- 1
Provision the dependencies
Pug needs three backing services: PostgreSQL for accounts and project config, ClickHouse as the event store, and NATS for the async pipeline. Run them as managed services or containers — wherever you already operate infrastructure.
- 2
Deploy the Pug binary
Pug ships as a single Go binary that runs the API and every worker in one process. Point it at your Postgres, ClickHouse, and NATS connection strings and start it. One process keeps the operational surface small.
- 3
Create a project and keys
In the dashboard, create a project. You get a public key (pub_…) for client SDKs and a private key (prv_…) for server-side tracking and reads. Keys are project-scoped, so nothing crosses your project boundary.
- 4
Install an SDK and initialize
Add the Web, Flutter, or Node SDK and call init() with your project ID, public key, and your Pug endpoint. Autocapture — page views, clicks, scrolls, form submits, rage and dead clicks — starts immediately.
- 5
Identify your users
Call identify(userId) when someone signs in. Their anonymous history merges into a single profile, and traits like plan or email become filters across every insight.
- 6
Verify in Live
Open the Live view and watch events arrive seconds after they happen, with page, device, and location already attached — the fastest way to confirm the integration is working before you build insights.
Setup questions, answered.
How hard is Pug to self-host?
The app itself is one Go binary, so the work is mostly standing up PostgreSQL, ClickHouse, and NATS and pointing the binary at them. There is no multi-service application tier to orchestrate.
Where are the exact install commands?
The authoritative, copy-paste setup — container images, environment variables, and version requirements — lives in the self-hosting docs, which stay current with each release. This guide is the conceptual map.
Why ClickHouse and not Postgres for events?
ClickHouse is a columnar database built for fast analytical scans over large event volumes. Postgres handles accounts and config; ClickHouse handles the events that Trends, Funnels, and Retention query.
Do I need NATS?
Yes — NATS is the async pipeline that decouples ingestion from enrichment and identity resolution, so a traffic spike queues rather than drops.
Is self-hosting free?
Yes, free forever under AGPL-3.0. You provide the infrastructure; there is no event cap or licensing fee.
Prefer zero ops?
The managed cloud runs the same code and is free during open beta — start there, and self-host whenever you’re ready. Your data is exportable either way.