Self-hosting

Your servers, your database, your data

Q: How much server do I need?

Falorb is designed for small-to-medium traffic on modest hardware. The reference deployment runs a portfolio of eight sites on a single small server alongside other services, which is why the ClickHouse configuration ships with capped memory, capped pools and bounded system logs rather than the defaults that assume a dedicated machine.

Q: Why three hostnames?

The collector, the dashboard and the MCP server run 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.

Q: What about backups?

The repository ships infra/backup.sh: incremental for ClickHouse, and a gzip dump for Postgres that is verified rather than assumed. Your event history is large and append-only; your control plane is small and mutates constantly, so they want different strategies.

Q: Can I deploy it on Coolify, Dokku or plain Docker?

Yes. Dockerfiles and a production compose file are in the repository and verified locally, with a deployment guide in infra/DEPLOY.md. The Caddy configuration is provided for anyone terminating TLS themselves; behind a platform proxy that terminates TLS at the edge, the app sets its own security headers so they follow it into any deployment.

Q: How do I upgrade?

Pull, install, run both migration runners, restart. Migrations are additive and the ClickHouse runner splits statements and substitutes placeholders itself. The historical backfill script assigns totals rather than incrementing them, so re-running it after an upgrade is safe.

There is no hosted Falorb to sign up for. That is not a gap in the product. It is what makes the privacy claims on this site structural rather than contractual. Nothing can leave a network that nothing is configured to leave.

Docker ComposeCaddy config includedBackup script included

Data stores3Postgres · Redis · ClickHouse

Services4collector · worker · dashboard · MCP

Collector p99<10 mspublishes, never blocks

LicenceMITcommercial use permitted

Shape

Four services and three stores

The split exists because the two kinds of data behave differently. Events are immutable and arrive fast; person profiles mutate constantly as merges, traits and interest scores land.

textthe stack

Browser ──▶ apps/ingest ──▶ Redis Stream ──▶ apps/worker ──┬──▶ ClickHouse   (events)
            (Bun + Hono)                                   └──▶ Postgres     (profiles)
            p99 <10ms                                              ▲
                                          packages/queries ────────┘
                                                  │
                              apps/web (dashboard) · apps/mcp (assistants)

Why Redis is in the middleThe collector's job is to answer the visitor's browser quickly and then stop. Publishing to a stream means a slow, restarting or temporarily unreachable ClickHouse never turns into a slow response on somebody else's website. The worker acknowledges the stream only after ClickHouse confirms the write, and reclaims entries a crashed consumer left behind.

Why two databasesEvents are append-only and high-volume, so they live in ClickHouse with monthly partitions, bloom-filter skip indexes and narrow per-dimension rollups. Profiles are small, heavily mutated and relational, so they live in Postgres. Identity is resolved at read time through a dictionary, which is why a merge is one insert and not a rewrite.

Hostnames

Three names, on purpose

a.yourdomain: The collector. Public, high volume, immutable one-year cache on the tracker script.
dashboard.yourdomain: The dashboard. Session cookies, strict Content-Security-Policy with a per-request nonce.
mcp.yourdomain: The MCP server, for assistants connecting remotely with a bearer API key.

Serving the collector from your own subdomain is also the practical answer to ad blockers: the lists target vendor hostnames, and this one is yours.

Falorb's endpoints panel listing the collector, dashboard and MCP hostnames configured for this deployment.

Operations

What running it actually involves

Backupsinfra/backup.sh does incremental for ClickHouse, and a verified gzip dump for Postgres. Two stores, two strategies, because one is large and append-only and the other is small and constantly rewritten.

Scheduled work11 jobs behind a scheduler using Redis distributed locks, watermarks and an overlap guard, so running two worker instances does not run every job twice.

RetentionPer-project retention enforced by a job every twelve hours, with a 25-month table-level TTL underneath it and an orphan prune for rows whose project is gone.

GeoIPA download script fetches and verifies the MaxMind City and ASN databases. They are not vendored, because the licence forbids redistribution and they go stale within weeks. Absent, the collector degrades to no geography rather than failing.

BackfillA manual backfill script for historical data that assigns totals rather than incrementing them, so re-running it after a half-finished attempt is safe.

Security headersSet by the applications rather than only in the reverse proxy, so they follow the deployment onto any platform, including ones that terminate TLS at the edge and never load your Caddyfile.

Commands

Production, in the same shape as development

bashdeploy

# production stack
docker compose -f infra/docker-compose.production.yml up -d

# migrations are additive and safe to re-run
pnpm --filter @falorb/db migrate
pnpm --filter @falorb/db ch:migrate

bashcheck

# is the pipeline actually intact?
node scripts/loadtest.mjs

# do all the scheduled jobs run?
pnpm --filter @falorb/worker verify:jobs

# collector readiness: redis, geo, tracker
curl https://a.yourdomain/health

Questions

Running it in production

How much server do I need?

Falorb is designed for small-to-medium traffic on modest hardware. The reference deployment runs a portfolio of eight sites on a single small server alongside other services, which is why the ClickHouse configuration ships with capped memory, capped pools and bounded system logs rather than the defaults that assume a dedicated machine.

Why three hostnames?

The collector, the dashboard and the MCP server run 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.

What about backups?

The repository ships infra/backup.sh: incremental for ClickHouse, and a gzip dump for Postgres that is verified rather than assumed. Your event history is large and append-only; your control plane is small and mutates constantly, so they want different strategies.

Can I deploy it on Coolify, Dokku or plain Docker?

Yes. Dockerfiles and a production compose file are in the repository and verified locally, with a deployment guide in infra/DEPLOY.md. The Caddy configuration is provided for anyone terminating TLS themselves; behind a platform proxy that terminates TLS at the edge, the app sets its own security headers so they follow it into any deployment.

How do I upgrade?

Pull, install, run both migration runners, restart. Migrations are additive and the ClickHouse runner splits statements and substitutes placeholders itself. The historical backfill script assigns totals rather than incrementing them, so re-running it after an upgrade is safe.

The full deployment guide is infra/DEPLOY.md in the repository.

One server, one afternoon

Bring up the stack, point three subdomains at it, and paste one script tag. After that the only recurring cost is the machine.

Quickstart What it costs