Self-hosting Falorb with Docker Compose

Three data stores and four services. The split is not arbitrary: events are immutable and arrive fast, so they live in ClickHouse, and person profiles mutate constantly as merges, traits and interest scores land, so they live in Postgres. Redis sits between collection and storage.

That middle layer is the part worth understanding before you deploy. The collector's job is to answer the visitor's browser and stop. It publishes to a Redis stream and returns; a worker consumes the stream and writes to ClickHouse, acknowledging only after ClickHouse confirms. A slow, restarting or briefly unreachable database therefore never becomes a slow response on somebody else's website.

One machine that can hold Postgres 17, Redis 7 and ClickHouse 25.3. Falorb is built for small-to-medium traffic on modest hardware, and the ClickHouse configuration in the repository ships tuned for a shared host rather than a dedicated one: capped memory, capped pools and bounded system logs.

• Node 22 or newer, and pnpm
• Docker and Docker Compose
• Bun, if you want to run the collector the way the reference deployment does
• A domain you can point three subdomains at

The compose file in the repository defines all three with the tuning already applied. Nothing else needs to exist yet.

FALORB_SALT_SECRET is what the daily-rotating IP hash salt is derived from. It is the reason no raw address is ever stored, so it must be set before anything collects.

BETTER_AUTH_SECRET ships as a low-entropy placeholder that warns on every boot. It signs session cookies, so rotate it before the first real account exists rather than after, because rotating it signs everybody out.

Two runners, because the two stores are genuinely different. Drizzle handles Postgres. ClickHouse has a purpose-built runner that splits statements, substitutes placeholders and redacts credentials from any error it reports.

Sign up in the dashboard first, then re-run the seed with your own address. Without it the seeded properties belong to an organization your account is not a member of, and you land in an empty portfolio wondering what went wrong.

The collector receives events and publishes. The worker consumes the stream, writes to ClickHouse, and runs the eleven scheduled jobs behind identity resolution, sessionization, path transitions, interest scoring, enrichment, alerts, GDPR requests and retention.

The collector, the dashboard and the MCP server go on separate subdomains. The collector is publicly reachable and high-volume, so an ad-blocker rule against it cannot take the dashboard down with it, and the two can be cached and scaled independently. Serving the collector from your own subdomain is also the practical answer to blocklists, which target vendor hostnames.

The repository ships a Caddyfile that terminates TLS and sets the cache headers, including a one-year immutable cache on the tracker script.

• a.yourdomain, the collector
• dashboard.yourdomain, the dashboard
• mcp.yourdomain, the MCP server, for assistants connecting remotely

Every claim in the repository has a command attached, and these are the ones worth running before you point real traffic at it. The load test is the important one: it asserts that every acknowledged event actually reached ClickHouse, which is the claim a collector is most tempted to fudge.

Backups are two strategies because the stores behave differently: the event history is large and append-only, the control plane is small and constantly rewritten. The repository ships infra/backup.sh with incremental ClickHouse and a verified gzip dump for Postgres.

Upgrades are pull, install, run both migration runners, restart. Migrations are additive, and the historical backfill script assigns totals rather than incrementing them, so re-running it after a half-finished attempt is safe.