Getting Started

Rybbit is an open-source, privacy-first alternative to Google Analytics. It provides a beautiful dashboard with real-time analytics, session replay, custom events, funnels, and geographic tracking. This guide walks you through setting up Rybbit on Eyevinn Open Source Cloud.

Prerequisites

  • An Eyevinn OSC account (free tier works for getting started)
  • A ClickHouse instance for analytics data storage
  • A PostgreSQL instance for application metadata
  • Optionally a Valkey (Redis) instance for caching and job queues

Step 1: Create the required database instances

Rybbit needs two databases: PostgreSQL for application data and ClickHouse for analytics data.

Create a PostgreSQL instance

Create a PostgreSQL instance and note down the user, password, and database name you set.

Create a ClickHouse instance

Create a ClickHouse instance. Do not set a user — leave the user field empty so ClickHouse uses the default user. Rybbit hardcodes the default username internally and has no configuration field to change it. You must set a password — Rybbit requires the ClickhousePassword field.

Important: After your ClickHouse instance is running, note its instance URL from the instance card. It will look like:

https://<name>.clickhouse-clickhouse.auto.prod.osaas.io

You will need this full URL for the Rybbit configuration (not just the IP address).

Step 2: Create a Rybbit service secret

Create a service secret for the BetterAuthSecret value. This should be a long random string used for encrypting authentication tokens. You can generate one with:

openssl rand -hex 32

Step 3: Create the Rybbit instance

When creating the Rybbit instance, fill in the configuration fields:

Field Value Notes
PostgresHost IP or hostname of your PostgreSQL instance From the PostgreSQL instance card
PostgresPort Port of your PostgreSQL instance From the PostgreSQL instance card
PostgresUser PostgreSQL username The user you set when creating the instance
PostgresPassword PostgreSQL password The password you set when creating the instance
PostgresDb PostgreSQL database name The database you set when creating the instance
ClickhouseHost Full URL of your ClickHouse instance Must be a full URL, e.g. https://myinstance.clickhouse-clickhouse.auto.prod.osaas.io. Do NOT use a bare IP address.
ClickhousePassword ClickHouse password Required. Must match the password set on the default user of the ClickHouse instance.
ClickhouseDb ClickHouse database name Optional. Defaults to default if not set.
BetterAuthSecret Random secret string Use the secret you created in Step 2
RedisHost Hostname of Valkey/Redis instance Optional, for caching and job queues
RedisPort Port of Valkey/Redis instance Optional
RedisPassword Valkey/Redis password Optional

Common mistakes

  • ClickhouseHost must be a URL, not an IP: The ClickHouse client library requires a full URL with protocol (e.g., https://myinstance.clickhouse-clickhouse.auto.prod.osaas.io). A bare IP like 172.232.137.101 will cause the app to crash with "ClickHouse URL is malformed".
  • Do not set a ClickHouse user: Rybbit connects as the default user and has no config field to change this. If you create the ClickHouse instance with a custom user, Rybbit cannot authenticate. Leave the user field empty when creating the ClickHouse instance.
  • ClickHouse password is required: Even though the ClickHouse instance creation does not enforce a password, you must set one because Rybbit requires ClickhousePassword. Set the password on the ClickHouse instance (on the default user) and use the same password in the Rybbit config.

Step 4: Access Rybbit

Once the instance is running, open the instance URL shown on the instance card. You can create your first admin account and start adding websites to track.

Optional configuration

Field Description
MapboxToken Mapbox API token for advanced geographic map visualizations
ResendApiKey Resend API key for transactional emails (password resets, invitations)
DisableSignup Set to true to prevent new user registrations