How to Use Rybbit: The Beginner's Guide (First Deploy, the DISABLE_SIGNUP Rule, Your First Site, and the Tracking-Script Lesson)

CodexFuse Team · 2026-11-01T07:15:38.028Z · 17 min read

Learn how to use Rybbit: deploy privacy-friendly web analytics with Docker, lock down signup, add your first site, install the tracking script, and track custom events.

What Is Rybbit?

Rybbit is an open-source, privacy-friendly web analytics platform that gives you Google Analytics-style dashboards without the surveillance baggage: no cookies, no consent banner, no cross-site tracking profiles. Learning how to use Rybbit means learning three things — deploying it on your own server with Docker, installing one small tracking script on your website, and reading a dashboard that respects your visitors.

The project lives at rybbit-io/rybbit on GitHub, where it holds around 13,200 stars and is licensed under the AGPL-3.0 license, and its official home is rybbit.com (the old rybbit.io address now redirects there). It is one of the strongest names in the privacy friendly analytics self hosted space — cookieless tracking, full dashboards, and a database you own. The latest release as of this writing is v2.9.2, published October 24, 2026, and the repository was pushed as recently as November 1, 2026 — this is a project that moves fast. If you are new to containers, our Docker beginner guide will get you up to speed before you touch the deploy commands below.

Whether you came here looking for a rybbit for beginners walkthrough or a rybbit docker deploy reference, this page covers the full beginner arc in one place — this rybbit tutorial takes you from an empty VPS to live dashboards: By the end you will have a working, self-hosted analytics stack you actually own.

Is Self-Hosting Your Analytics Worth It?

Yes — if you care about owning your data. Rybbit sits in a category called privacy-friendly analytics, and it exists because Google Analytics 4 made a quiet trade with site owners: free dashboards in exchange for building Google's ad profile. A self-hosted Google Analytics alternative flips that trade: the analytics server is yours, the data stays in your database, and your visitors get tracked without cookies or consent banners.

Rybbit's own documentation lays out the comparison against the big names in a feature table. Here is the honest version of what that table says, sourced from the official docs:

Source: the official Rybbit comparison documentation at rybbit.com/docs/comparison.

The practical takeaway: Rybbit gives you close to the depth of a product-analytics suite while staying cookieless and self-hostable — which is what makes it a serious self hosted Google Analytics alternative. It is exactly the combination neither GA4 (deep, but surveillance) nor Plausible's free tier (private, but shallow) offers. One honest caveat from those same docs: session replays and custom SQL dashboards are Pro-tier features in the cloud, but self-hosting unlocks everything — the docs literally say a check means the feature is in every current Rybbit Cloud plan and in self-hosted Rybbit.

What Do You Need Before You Install Rybbit?

You need three things: a VPS with Docker installed, a domain name pointed at that server, and about 30 minutes. Rybbit's self-hosting stack is heavier than the old SQLite-era analytics tools — the current official docker-compose.yml runs ClickHouse for event analytics, PostgreSQL 17 for application data, and Redis for sessions and cache. That sounds intimidating, but the official setup script handles all of it.

If you have never rented a server before, start with our plain-English explainer on what is VPS hosting, then come back here. The server should have at least 2 GB of RAM — ClickHouse is the hungry one in this stack.

How Do You Deploy Rybbit With Docker?

You deploy it with the official setup script, which generates your secrets, pulls prebuilt images, and starts everything behind Caddy. Here is the full arc, step by step:

1. Point your DNS. Create an A record for your domain (for example, analytics.yoursite.com) pointing at your VPS. Caddy needs the domain live to fetch a TLS certificate.
2. Clone the repository. git clone https://github.com/rybbit-io/rybbit.git, then cd rybbit.
3. Make the setup script executable. chmod +x setup.sh.
4. Run the setup. ./setup.sh analytics.yoursite.com — substitute your real domain. The script generates a .env file with a random secret and pulls the images.
5. Start the stack. docker compose --profile with-webserver up -d. This launches the backend (ghcr.io/rybbit-io/rybbit-backend:latest), the client (ghcr.io/rybbit-io/rybbit-client:latest), ClickHouse, PostgreSQL, Redis, and Caddy 2.10.0.
6. Wait for the containers to settle. ClickHouse especially takes a minute on first boot. Check with docker compose ps.
7. Visit your domain. Open https://analytics.yoursite.com/signup and create the admin account. This first account is the admin.
8. Log in and add your first website. The dashboard will hand you a site ID and the tracking script (more on both below).
9. Install the tracking script on your website (covered in the next sections) and confirm data arrives in the real-time dashboard.
10. Lock registration. Set DISABLE_SIGNUP=true in your .env and restart — this is non-negotiable and gets its own section next.

The backend binds to port 3001 and the client to 3002, both localhost-only — Caddy is the only thing facing the internet, which is the correct shape. If you want to tweak the generated compose file, our Docker Compose generator can help you sanity-check service definitions, and our Caddy beginner guide explains the reverse proxy doing the TLS work here.

One note for map lovers: the .env.example in the repository includes an optional MAPBOX_TOKEN that switches the geography views to 3D maps. Skip it on day one; the built-in maps are fine.

The DISABLE_SIGNUP Rule: Lock Registration Before You Expose the Instance

Disable signup before your instance is reachable from the public internet. This is the number-one security miss with self-hosted Rybbit, and the reason is simple: the default in .env.example is DISABLE_SIGNUP=false, which means the /signup page happily creates new accounts. On a public analytics instance, "new accounts" means strangers.

The correct sequence is: run setup, create your own admin account first, then set DISABLE_SIGNUP=true in .env and restart the stack. Self-hosted Rybbit does not send email — there are no invitation emails and no "forgot password" flow — so the admin creates users directly inside the app. That design makes open registration even more dangerous, because there is no email-verification gate to catch abuse. Lock the door; keep the key.

How Do You Add Your First Website?

You add it from the dashboard, and Rybbit hands you everything you need. After logging in as admin, go to the sites area and add your website with its real domain. Rybbit creates the site with a unique site ID, and shows you the tracking snippet with that ID already filled in.

Organizations can hold unlimited sites, so a single instance can serve your blog, your side projects, and your clients' sites alike. Each site gets its own script URL and its own dashboard, so data never mixes.

How Do You Install the Rybbit Tracking Script?

You paste one script tag into the <head> of every page, with your site ID in the URL. The official form is:

<script src="https://analytics.yoursite.com/api/script.js?siteId=YOUR_SITE_ID" defer></script>

Two details matter here. First, the site ID goes in the script URL as a query parameter. An older data-site-id attribute form still works, but the docs recommend the URL form because script optimizers like WP Rocket, Perfmatters, and FlyingPress can strip data-* attributes and silently break tracking. Second, the defer attribute keeps the script from slowing your page load.

Now the ad-blocker reality, said once: some ad blockers will block analytics scripts regardless of how privacy-compliant they are, and Rybbit's own docs admit this openly. The official recommendation is to proxy the script through your own domain — the docs include a Proxy Guide with examples for Next.js, Nginx, and Caddy. Since the script then loads from a first-party URL, far fewer blockers touch it, and your numbers get meaningfully more accurate. This is the honest trade-off of the lightweight-analytics lane: privacy compliance alone does not guarantee the data arrives.

How Do You Track Custom Events in Rybbit?

You track custom events with one JavaScript call, and this is the moment self-hosting starts paying for itself. Pageviews alone rarely justify running your own analytics server — events are what turn a dashboard into decisions. The API is:

window.rybbit.event("Item Added To Cart", { itemId: "PROD123", price: 49.99, category: "Clothing" });

That example is straight from the official track-events docs: the first argument is the event name (maximum 256 characters), the second is a JSON object of properties (maximum 2048 characters — larger payloads are rejected). Events feed directly into funnels, goals, and filters, which is where they earn their keep.

Here is the classic e-commerce arc to wire up first: Product Viewed on the product page, Item Added To Cart on the add-to-cart click, Checkout Started on the checkout page, and Purchase on the order confirmation. Then build a funnel out of those four steps and watch exactly where buyers leak out. That is the whole rybbit event tracking model: one function call, one event name, one JSON object of properties — and the dashboard does the rest. For sites where you cannot run JavaScript, the docs offer a no-JS option via data-rybbit-event attributes on HTML elements.

How Do You Read the Rybbit Dashboard?

You read it from the top down: traffic first, behavior second, intent last. The dashboard opens on sessions, unique users, pageviews, bounce rate, and session duration — the five numbers every analytics tool shows — with a real-time view of what is happening right now. That is the traffic layer, and it answers "how many".

The behavior layer answers "what did they do": funnels (built from a mix of page paths and your custom events, computed in real time with no sampling), retention analysis, and user journeys drawn as Sankey diagrams between 2 and 6 steps deep. Goals let you mark the conversions that matter, session replays show you exactly what a visitor saw, and JS error tracking catches the front-end bugs your users silently endure. Web vitals are available as an opt-in layer on top.

The slicing layer is the filters: more than 15 dimensions, from referrers and devices to your own custom event properties, plus three levels of geography (country, then region, then city) with map visualizations. And because the stack runs ClickHouse underneath, the advanced play is autocapture of clicks and forms plus the Pro-tier custom SQL dashboards for questions the UI cannot express.

Rybbit vs Plausible vs PostHog: Which One Do You Actually Need?

The right tool depends on the lane you are in, so let me draw the lines. In the rybbit vs plausible debate, the official comparison table says it plainly: Plausible's free Community Edition has very limited features compared to its cloud version, and per that same table, Plausible lacks session replays, funnels, error tracking, retention, and user journeys while offering only limited custom events. If you want the Plausible philosophy (tiny, privacy-first) plus the depth of a bigger suite, Rybbit is that combination.

Rybbit vs PostHog is a different question entirely, because PostHog plays a different game: full product analytics with feature flags, cohorts, and session replay aimed at product teams. Our PostHog beginner guide covers that lane — reach for PostHog when you are analyzing a product's user base; reach for Rybbit when you want privacy-friendly website analytics you can host in an afternoon. Never rivals: lightweight-privacy versus product-analytics.

And rybbit vs umami? The docs do not publish a head-to-head table, so here is what is verified: Rybbit ships official data importers for Umami, Simple Analytics, and Plausible, which means the project expects people to migrate from exactly those tools. If you are already on Umami and only need pageview counters, you may not need to move; if you have outgrown it and want funnels, replays, and error tracking without leaving the self-hosted world, the import path is paved.

Should You Self-Host Rybbit or Use Rybbit Cloud?

Self-host if you want every feature and full data ownership; use the cloud if you want analytics in minutes. The official docs frame the trade-off this way: a rybbit self hosted install takes roughly 30 to 120 minutes of setup plus regular updates, while the cloud gets you to first data in minutes with zero maintenance.

Cloud pricing, from the official pricing page: a 7-day free trial, then Standard at $13 per month billed annually (100,000 monthly pageviews, up to 5 websites, 3 team members) and Pro at $26 per month billed annually (unlimited websites and team members, session replays, 5-year data retention), with custom Enterprise above that. Only the annual-billed prices were published at the time of writing; monthly billing exists but the amounts were not confirmed.

The self-hosted trade-off most people miss: your instance does not send email. No invitation emails, no password resets — the admin creates users directly. That is fine for a solo operator or a small team, and it is one more reason the DISABLE_SIGNUP rule matters: with no email verification in the loop, an open signup page is an open door.

Moving to Rybbit From Another Analytics Tool

You import, not rebuild. Rybbit's documentation lists official importers for Umami, Simple Analytics, and Plausible, so your historical pageview data can move with you. The sane migration order is: deploy Rybbit alongside your current tool, run the importer, install the Rybbit script in parallel for a week to confirm the numbers agree, and only then remove the old script. Two analytics scripts for seven days is a small price for a verified cutover.

Sources

Every fact in this guide was verified against a source fetched on November 1, 2026: the GitHub API entry for rybbit-io/rybbit (stars, license, activity), the GitHub Releases API (v2.9.2, October 24, 2026), the official docker-compose.yml (ClickHouse, PostgreSQL 17, Redis, images, ports), the official .env.example (DISABLE_SIGNUP default, MAPBOX_TOKEN), the official self-hosting docs (setup.sh flow), the official tracking-script docs (script form, ad-blocker note, proxy guide), the official track-events docs (event API, limits, no-JS attributes), the official comparison docs (GA4/Plausible/Cloudflare table, Pro-tier note, importers), the official pricing page (tiers and pageview limits), the official self-host vs cloud docs (setup time, no-email note), the project README (dashboard capabilities), and the independent guide Rybbit: Analytics Without the Surveillance (whiteRavens, August 2026).

Frequently Asked Questions

Is Rybbit really free?

The software is free and open source under the AGPL-3.0 license, and self-hosting it costs you only your server. Rybbit also sells a cloud version starting at $13 per month billed annually for 100,000 monthly pageviews. Self-hosting additionally unlocks every feature, including Pro-tier ones like session replays.

Does Rybbit use cookies or need a consent banner?

No. Rybbit is cookieless by design, which is why it markets itself as privacy-friendly analytics and why most sites can run it without a consent banner. Note that ad blockers may still block the script regardless — the official fix is proxying it through your own domain.

Can Rybbit replace Google Analytics?

For website analytics, yes: sessions, pageviews, funnels, retention, user journeys, goals, and custom events are all there. What you give up is Google's cross-site identity graph and its ad-platform integrations — which, for most site owners, is the point of switching.

How is Rybbit different from Plausible?

Plausible is deliberately minimal; Rybbit is the same privacy philosophy with a much deeper feature set — funnels, session replays, error tracking, retention, and user journeys, all self-hostable with no feature limits. Plausible's free Community Edition is also notably limited compared to its cloud version, per Rybbit's own comparison docs.

What database does self-hosted Rybbit use?

The current official stack uses ClickHouse for event analytics, PostgreSQL 17 for application data, and Redis for sessions and cache. Older third-party guides mention simpler setups, but the current master compose file has no SQLite anywhere — follow the official setup.sh flow.