Swetrix/swetrix v5.0.0

on GitHub

🔥 Major updates

UI Redesign

We’ve given Swetrix a fresh, more scalable interface built for easier navigation.

• Analytics dashboard: navigation has moved to vertical tabs, making it easier to add and access more reports without cramming the top bar.
• Projects dashboard: now cleaner and less cluttered, with built-in traffic charts so you can instantly understand how each project is performing at a glance.
• Polish across the app: we’ve refined a lot of the smaller UI details - tables, buttons, dropdowns, spacing, and general layout to make everyday use feel smoother and more consistent.

Profiles

You can now analyse long-term user behaviour and link distinct sessions to anonymous user profiles. This allows for much more accurate retention analysis and user journey mapping, and are extremely useful for calculating accurate MAU metric.

We built this with a privacy-first architecture. We do not use cookies, and we do not store raw IP addresses for profile tracking. Instead, we use a combination of non-identifiable signals (like user agent) and a salt to generate a completely irreversible identifier (a similar mechanism to how we track sessions, but with a different, longer living salt).

For those who need even more precision (and have user consent), we've added the ability to pass your own custom User IDs from the tracking script, giving you the most accurate analysis possible for logged-in users.

Learn more about Profiles.

Goals

You can now define your own conversion goals to measure how many visitors complete specific actions on your website - like a sale, visiting a specific page or triggering a specific custom event.

Goals report you the exposure of your total traffic to the events you defined in them (conversions) - in a simple dashboard.

Learn more about Goals.

Feature Flags

Feature flags allow you to toggle features on and off for your users without deploying new code. This is useful for rolling out new features gradually, testing in production, or quickly disabling a feature if something goes wrong.

Learn more about feature flags.

CAPTCHA

This release also includes a selfhostable version of our CAPTCHA solution.

Swetrix Captcha is a privacy-first alternative to Google reCaptcha. Unlike traditional CAPTCHAs that require users to identify objects in images or solve puzzles, Swetrix CAPTCHA uses a Proof of Work (PoW) mechanism.

In order to solve Swetrix Captcha a user's comuter needs to perform a cryptographic calculation (Proof of Work) in the background. This requires a small amount of computational power from the user's device, which is trivial for a legitimate user but computationally expensive for bots trying to spam at scale.

Learn more about Swetrix Captcha.

🙂 Minor changes

• You can now pin / unpin projects in your dashboard.
• Added an optinal Website URL setting to your project settings. If you add it, it will activate tiny but nice features like links to your website pages in the Pages panel or session pageflow, as well as display your website's favicon in your analytics dashboard.
• Reworked custom events UI in your analytics dashboard. On the traffic tab you will now see your custom events table, as well as a chart to see when these events were fired. Below these components you will also see reworked custom events & pageviews metadata tables to easier navigate them.

• Swetrix is now fully using server-side rendering - it's a much more stable and reliable product now.
• Added sorting options for your projects in the dashboard view, as well as a time period selector for the aggregated data view.
• Performance optimisations for analytics data inngest (same Swetrix instance can now handle more incoming events).
• For folks who use OIDC auth: you can now set OIDC_PROMPT variable, default value is select_account.
• We enabled compression for analytical data in Clickhouse - it should result in savings to your storage.
• (applicable to advanced users) You can now configure what header you want to use to get the IP address for incoming analytics requests. By default, we attempt to get request IP address from x-forwarded-for, but you can set it to any custom value by changing the CLIENT_IP_HEADER variable, to something like cf-connecting-ip, x-real-ip, etc. Consequently, the CLOUDFLARE_PROXY_ENABLED variable is not removed.

🔧 Fixes

• fix: some users saw login page flasing for a few milliseconds when they opened the app (#462)
• fix: reduce the size of the bundle by removing unnecessary libraries (#448)

Upgrading to Swetrix v5 (from v4.1.0)

First, you need to stop Swetrix CE: docker compose down

1. Update your compose.yaml file & configuration

1) Create an nginx/config file in your selfhosting folder root

You may either do a git pull to pull the latest changes, or just manually copy it / replace existing one with a new one from our selfhosting repository.

2) Add a new nginx service to your compose.yaml

Make sure that your compose.yaml now contains the following service

  nginx-proxy:
    image: nginx:1.29.4-alpine
    restart: always
    depends_on:
      swetrix:
        condition: service_healthy
      swetrix-api:
        condition: service_healthy
    links:
      - "swetrix-api"
      - "swetrix"
    ports:
      - "80:80"
    volumes:
      - ./nginx/config:/etc/nginx/conf.d/default.conf

3) Remove unused variables & properties

Make sure that the following variables are updated in your compose.yaml file

Changes to the swetrix service:

Replace image: swetrix/swetrix-fe:v4.1.0 with image: swetrix/swetrix-fe:v5.0.1

Remove:

ports:
      - "80:3000"

In environment, replace API_URL=${API_URL} with BASE_URL=${BASE_URL}

Changes to the swetrix-api service:

Replace image: swetrix/swetrix-api:v4.1.0 with image: swetrix/swetrix-api:v5.0.1

Remove:

ports:
      - "8080:5005"

Remove the - CLOUDFLARE_PROXY_ENABLED environment variable

For reference, see our current live compose.yaml file here.

4) Update your .env file

Add a BASE_URL variable with a URL where you host your Swetrix instance.

2. Start your docker container

Run the docker compose up -d command. This will pull up the Swetrix CE v5 release.

If you open your dashboard now, it will not work. This is expected as you still need to do a data migration to synchronise the new code with the database tables.

3. Run database migration scripts

In order to upgrade to Swetrix v5, you will need to run database migrations scripts. But first, your compose.yaml file should be set to the latest Swetrix versions and they are already installed on your machine.

To perform the migrations, you need to run the following commands in your selfhosting folder:

docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2025_12_07_goals.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2025_12_10_feature_flags.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2025_12_14_data_compression.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2025_12_14_pinned_projects.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2025_12_24_website_url.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_01_02_captcha.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_01_02_salt.js
docker compose exec swetrix-api node migrations/clickhouse/2025_12_02_profile_id.js
docker compose exec swetrix-api node migrations/clickhouse/2025_12_08_feature_flags.js
docker compose exec swetrix-api node migrations/clickhouse/2025_12_11_experiments.js
docker compose exec swetrix-api node migrations/clickhouse/2025_12_14_data_compression.js
docker compose exec swetrix-api node migrations/clickhouse/2025_12_15_revenue.js

If you don't see any Query ERROR messages written to your console, this indicates that the migrations went well and Swetrix v5 is ready to use.

After performing the migrations above, you should run docker compose restart

4. Update your tracking script configuration

Since Swetrix now uses a single URL both for backend and web UI, you should change the apiUrl in your swetrix.init() to make it work.

For example, if in Swetrix CE v4 your script looked like:

swetrix.init('wA17aa6kbcYj', {
  // the https://api.swetrix.example.com is what was API_URL variable in `compose.yaml` earlier
  apiURL: 'https://api.swetrix.example.com/log',
})

You should change it to:

swetrix.init('wA17aa6kbcYj', {
  // the https://swetrix.example.com is the new BASE_URL variable in `compose.yaml` earlier
  apiURL: 'https://swetrix.example.com/backend/log',
})

🎉 That's it, enjoy selfhosting Swetrix! Join our Discord community for more updates & discussions about Swetrix.

Our work would not be possible without your support, and we hope you will love this release!