Quick start

This guide will walk you through setting up your own instance of Rybbit using our setup script. If you want to manually setup Rybbit using the Docker Compose file, check out our Manual Docker Compose Setup guide.

Prerequisites

Before you begin, ensure you have the following:

A Server: Try to get one with at least 2GB of RAM.

We use Hetzner for everything. Use our referral link to get a 20 dollars of credits. It should last you almost half a year. The AMD CX11 is a good choice for ~$4/month.
A Domain Name: You'll need a domain or subdomain (e.g., tracking.yourdomain.com) pointed to your VPS's IP address. HTTPS is required because browsers block tracking scripts served over insecure HTTP.

This guide has been tested on Ubuntu 24 LTS (x86_64). If your server is ARM, it must be at least ARMv8.2-A for Clickhouse support.

Setup Steps

Point Your Domain to Your VPS

Configure your domain's DNS settings to point to your VPS's public IP address. This usually involves:

Finding your VPS's public IPv4 address (from your hosting provider, e.g., Hetzner).
Logging into your domain registrar or DNS provider (e.g., GoDaddy, Namecheap, Cloudflare).
Adding an A record:
- Host/Name: Your desired subdomain (e.g., tracking) or @ for the root domain.
- Value: Your VPS's IPv4 address.
- Proxy Status: When using Cloudflare, either:
  - Set to "DNS only" (recommended for most setups)
  - Or if keeping the proxy enabled, set SSL/TLS encryption mode to "Full" or "Full (strict)" in your Cloudflare dashboard under SSL/TLS settings

If you keep Cloudflare's proxy enabled and your domain has other services not running on HTTPS, using Full or Full (strict) mode might cause issues with those services. In such cases, either use "DNS only" mode or ensure all your services support HTTPS.

DNS changes might take some time to propagate globally. Use DNS Checker to verify.

Install Docker Engine

Connect to your VPS via SSH.

Follow the official Docker Engine installation instructions for your Linux distribution: https://docs.docker.com/engine/install/

Clone the Rybbit Repository

Clone the project repository from GitHub (Git is usually pre-installed on most server distributions):

git clone https://github.com/rybbit-io/rybbit.git
cd rybbit

Run the Setup Script

The repository includes a setup script that configures the necessary environment variables (including generating a secure secret) and starts the application using Docker Compose.

Important: Make all scripts executable before proceeding!

chmod +x *.sh

Run the setup script, replacing your.domain.name with the domain or subdomain you configured in the prerequisites:

./setup.sh your.domain.name

If you want to enable 3D map visualizations, you can add the --mapbox-token flag:

./setup.sh your.domain.name --mapbox-token YOUR_MAPBOX_TOKEN

The script will create a .env file and then build and start the containers. This might take a few minutes the first time.

By default, we assume you are on a blank VPS and automatically setup a Caddy webserver. If you want to use your own webserver or need more control over the setup, check out:

Manual Docker Compose Setup - For users with existing reverse proxies or deployment tools
Advanced Self-Hosting Guide - For custom configurations and Nginx setup

Once the services are running and DNS has propagated, Caddy (the webserver) will automatically obtain an SSL certificate for your domain.

Open your browser and navigate to https://your.domain.name/signup (using the domain you provided to the setup script).

Create your admin account. You can then log in and start adding your websites!

If you run into any issues or need help, feel free to join our Discord community!