Getting Started

Welcome to the Basicrum documentation! This guide will help you get started with Basicrum, an open-source Real User Monitoring (RUM) system. Whether you're a developer looking to integrate RUM into your application or an operator interested in deploying Basicrum, this guide has you covered.

If you prefer to self-host Basicrum on your own infrastructure, we have a comprehensive Dokploy Deployment Guide that walks you through the process of deploying Basicrum using Dokploy, a self-hosted PaaS that simplifies Docker container deployment. This guide covers everything from setting up the architecture to configuring the services and environment variables needed to get Basicrum up and running on your servers.

How it works

    ┌──────────────────────┐                              ┌──────────────────────┐
    │  End user's browser  │                              │   Admin's browser    │
    └──────────────────────┘                              └──────────────────────┘
                │ beacon                                              │ HTTPS
                ▼                                                     ▼
    ┌──────────────────────┐                              ┌──────────────────────┐
    │    beacon_service    │                              │       Frontend       │
    │        (Rust)        │                              │      (Next.js)       │
    └──────────────────────┘                              └──────────────────────┘
                  writes                                              │ ts-rest API
                │                                                     ▼
                │                                         ┌──────────────────────┐
                │                                         │       Backend        │
                │                                         │      (Node.js)       │
                │                                         └───────────│──────────┘
                │               reads                                 │   reads/writes
                │                       ┌─────────────────────────────┴─────┐
                ▼                       ▼                                   ▼
    ┌──────────────────────────────────────────────┐            ┌──────────────────────┐
    │                  ClickHouse                  │            │      PostgreSQL      │
    │                 (RUM events)                 │            │    (users, orgs)     │
    └──────────────────────────────────────────────┘            └──────────────────────┘

• boomerang.js runs in the end user's browser and sends beacon data on page load/unload. We provide libraries around it to support many different types of frameworks: Magento, Wordpress, NPM, and more. Link
• beacon_service our Rust service that receives beacons and writes them to ClickHouse.
• ClickHouse stores the raw RUM events in a time-series database.
• PostgreSQL stores users, organizations, and other application data.
• backend serves the dashboard's API: reads from ClickHouse, reads/writes Postgres.
• frontend is the dashboard, talking to the backend through the shared api_contract.

If you want to run Basicrum locally, follow the instructions in the Local Development guide.