v4.1.0

Warning

This release contains breaking changes that require migrations, so please read these instructions carefully if you are upgrading from a previous version, otherwise your installation will not work properly.

What changed:

🔥 Major updates

• Referrer grouping - now in the Traffic sources you will see links grouped by it's top level domain. For example, if you have many different referrers from different Reddit posts, you'll see all of them grouped by Reddit name. If you click on a top level domain - you'll see a list of all the links from this domain. Learn more.
• Annotations - You can now mark important events on your charts to remember why traffic patterns changed. Learn more.
  
• Added traffic exclusion by country. Learn more.

🙂 Minor changes

• New filters experience - search filters modal now allows you to filter by contains / not contains, and overall it's much easier to apply filters using this view.
• Add autorefresh (every 30 seconds) functionality to analytics dashboard.
• Show/hide toggle on password input fields.
• A few other UI improvements around the app.

🔧 Fixes

• Filter for Pages leads to crash (bug report from our Discord channel)

Upgrading to Swetrix v4.1.0 (from v4.0.6)

Important

You will need to perform a database migration. Please make sure you read these instructions through to the end to make sure you've updated properly and to avoid losing any data.

1. Run database migration scripts

Warning

Please make sure you always back up your data! Especially before migrating, to prevent data loss if something goes wrong.

In order to upgrade to Swetrix v4.1.0, 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_11_29.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2025_11_30.js

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

After performing the migration, you can run docker compose restart and Swetrix should be good to go!

🎉 That's it, enjoy selfhosting Swetrix! Let us know if you find any bugs or have any feedback for us and join our Discord.

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

v4.0.6

What's Changed

🔧 Fixes

• Fix: "Check if password is leaked" did not work
• Fix: Pageview properties (metadata) panel only displays 1 key
• Fix: Auth redirects issues (if you go to a project settings page, for example, it would redirect you to /login, and then to /dashboard); now the auth redirects are handled correctly and do not redirect when it's not needed

🔸 Misc

• Refactored and simplified authentication
• Improve metadata table usability

v4.0.5

What's Changed

🙂 Minor changes

• Analytics dashboard: Add contains / not contains filters support

🔧 Fixes

• Fix: Applying any null-able filter (Not set, Unknown, etc.) did not work
• Fix: Search for countries and locales did not work properly

v4.0.4

What's Changed

🙂 Minor changes

• Use unique Map view colour styles for traffic, performance and errors modes

🔧 Fixes

• Map view performance optimisations
• Fix: On mobile, the live visitors dropdown and time / period selector menus are not visible on open (rendered behind the chart panel)

v4.0.3

What's Changed

🙂 Minor changes

• Add support for 75th percentile for Performance analytics
• Add account deletion functionality
• Add 'log out from all devices' functionality
• Add transitions & animations throughout the app; reuse same UI elements for nicer experience

🔧 Fixes

• Fix: When going from a specific session back to sessions list, it does not fetch first 30 sessions (same fix for errors view too)

v4.0.2

What's Changed

🙂 Minor changes

• Update Funnels page UI to be in line with the rest of the dashboard
• Add funnels conversions stats and start / end numbers above the chart (e.g. 4-step funnel • 0.19% conversion rate, Start: 516 → End: 1)

🔧 Fixes

• Fix: Opening Errors tab -> going to an error -> going back - results in an empty errors list ("No events yet" message)
• Fix: Clicking on a Funnel card settings opens the funnel analytics page instead of it's settings
• Fix: If one of the funnel steps are at 0, the subsequent funnel steps are displayed as null%
• Remove dotenv advertisements in console when running migrations

v4.0.1

This release is a patch for the v4.0.0 release that fixed a cache issue related to the migrations.

If you're upgrading from v3, please read the v4.0.0 release notes as they contain important instructions on how to migrate

v4.0.0

⚡️ Introducting Swetrix CE v4 - new UI, OIDC, project sharing and more!

Warning

This is a major release that contains breaking changes that require migrations and configuration changes, so please read these instructions carefully if you are upgrading from previous versions, otherwise your installation will stop working properly.

What changed

Dashboard redesign

We have fully redesigned the analytics dashboard for faster navigation and clearer insights:

• Combined smaller panels into larger, more consistent sections for easier navigatio
• Replaced panel pagination with a "Details" view - a full, scrollable table with search to see all the data at once
• Browser and OS version breakdowns are now easily accessible via the chevron next to each item
• Made top bar on the dashboard page sticky and less cluttered
• Chart improvements: better ticks calculation, added subtle horizontal lines to the background and other minor design updates

The Sessions tab of the dashboard has also been improved:

• We've added an ability to select a specific time range on the graph to view the events that occurred during that period.
• Sessions list now shows how many pageviews / custom events / errors happened within a session.
• Session events are now displayed with seconds precision.
• Added a "Live" indicator on sessions that are live.
• Added a "Refresh" button to refresh selected session.

The UI has also been refreshed in many other places thorughout the application, including various changes to buttons, inputs, tabs and other UI elements.

Account system

Previous versions of Swetrix CE supported only a single user per deployment and required credentials to be set via .env variables.

We’ve introduced a built‑in, multi‑user account system with native registration and sign‑in that you control (you can enable or disable sign‑ups). Users can update their account details, API keys or delete their account directly from the Swetrix CE interface.

* you can now remove EMAIL / PASSWORD from your .env file; all the existing projects on your deployment will be automatically assigned to you (the first user) when you register on your Swetrix CE deployment

OpenID Connect (OIDC) support

Added OIDC authentication for single sign‑on (SSO) with any OIDC‑compliant identity provider (e.g., Google, Azure AD, Okta, Keycloak). Can be configured with environment variables (see OIDC setup docs); and can work together with the existing authentication.

Project sharing

You can now invite other Swetrix CE users to collaborate on your projects. Assign roles to control access - admin (full management) or viewer (read‑only) - and transfer ownership when needed.

🙂 Other updates

• The dashboard now displays the hostname data
• Added custom metadata support to error events
• Added stacktraces support to error events
• You can now select time periods by zooming the main chart (and on the session view zooming chart filters out parts of the pageflow for easier navigation)
• Added onboarding to get you up and running faster
• The geolocation map view now supports zoom
• Added 'Last activity time' feature to sessions view
• Added All time period support for Filters and Errors views
• Added 'Forgot password' functionality
• Added Entry / Exit pages support
• Added Client Hints support for more accurate analytics (used alongside with User-Agent headers)
• SMTP support (for forgot password functionality, project sharing, etc.)
• Large timeframes now support more granulare time periods (for example, you can now view 12 months worth of data aggregated by the 'day' period)
• When applying filters, changing timeframes or doing other actions to dashboard, you can now go back and forward using browser native 'Go back' button
• On session pageflow display event time with second granularity
• Removed custom fonts in favour of default system one
• If you misconfigure your Swetrix CE instance so it won't be able to reach the backend - we'll notify you about it (#393)
• The Swetrix CE configuration helper (configure.sh) now auto-installs the Docker and Docker Compose dependencies for you if they're not installed
• Clear branding distinction between the selfhosted Swetrix Community Edition (CE) and the Swetrix Cloud edition
• 100% translations coverage
• Updated dependencies

🔧 Fixes

• HTTP 500 error when applying non-existent filters to Errors dashboard tab
• Stop throwing 400 error for known bot requests (#371)
• Fixed an issue that caused HTTP requests to delete projects data to hang up
• Fixed a rare error that caused reporting dashboard to crash because some data had unset session identifiers in them
• Fixed cumulative chart 0 events gaps issue
• Fixed discrepancy between the live users counter and sessions list on the analytics dashboard page

Upgrading to Swetrix CE v4 (from v3)

Important

You will need to perform a database migration and configuration changes. Please make sure you read these instructions through to the end to make sure you've updated properly and to avoid losing any data.

In order to upgrade to Swetrix v4, you need to perform the following actions:

1. Shut down your Swetrix docker container

In the self-hosting folder where your compose.yaml file is located, run the docker compose down command.

2. Update compose.yaml and .env configuration

In the compose.yaml you need to perform the following changes:

1. For swetrix image, update the following:

• Change swetrix/swetrix-fe:v3.3.1 to swetrix/swetrix-fe:v4.0.1

2. For swetrix-api image, update the following:

• Change swetrix/swetrix-api:v3.3.1 to swetrix/swetrix-api:v4.0.1
• Remove the following variables:

-      - JWT_ACCESS_TOKEN_SECRET=${JWT_ACCESS_TOKEN_SECRET}
-      - JWT_REFRESH_TOKEN_SECRET=${JWT_REFRESH_TOKEN_SECRET}
-      - EMAIL=${EMAIL}
-      - PASSWORD=${PASSWORD}
-      - API_KEY=${API_KEY}

• Add the following new variables:

+      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
+      - DISABLE_REGISTRATION=${DISABLE_REGISTRATION}
+
+      # Emails configuration (SMTP)
+      - SMTP_HOST=${SMTP_HOST}
+      - SMTP_PORT=${SMTP_PORT}
+      - SMTP_USER=${SMTP_USER}
+      - SMTP_PASSWORD=${SMTP_PASSWORD}
+      - FROM_EMAIL=${FROM_EMAIL}
+      - SMTP_MOCK=${SMTP_MOCK}
+
+      # OIDC configuration
+      - OIDC_ENABLED=${OIDC_ENABLED}
+      - OIDC_ONLY_AUTH=${OIDC_ONLY_AUTH}
+      - OIDC_DISCOVERY_URL=${OIDC_DISCOVERY_URL}
+      - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
+      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}

In your .env file you can remove all the variables that you've removed from the compose.yaml earlier.

It is IMPORTANT (!) that you set the SECRET_KEY_BASE variable to some secure, random string. You can generate such random string using the openssl rand -base64 48 command. You MUST do this to make sure your Swetrix CE deployment is safe and works properly!!

3. Update Redis image to redis:8.2-alpine

3. Start your docker container

Run the docker compose up -d command. This will pull up the Swetrix CE v4 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.

4. Run database migration scripts

Warning

Please make sure you always back up your data! Especially before migrating, to prevent data loss if something goes wrong.

In order to upgrade to Swetrix v4, you will need to run database migrations scripts. We assume that you've already followed the instructions above, so your compose.yaml file should already 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 command in your selfhosting folder:

docker compose exec swetrix-api node migrations/clickhouse/selfhosted_v3_to_v4.js

If you don't see any Query ERROR messages written to your console, this indicates that the migrations went well and Swetrix v4 is ready to use. You should not run this script more than once.

After performing the migrations, you can run docker compose restart and Swetrix should be good to go!

Warning

Because you've removed the EMAIL / PASSWORD variables from your .env file and the configuration, Swetrix CE will not work with your old credentials. Once you open your Swetrix CE deployment page, you need to create a new account on the Signup page. All of your previously created projects and website data will be assigned to this new account!
The same applies to your API keys - you will need to create new ones in the account settings if you have had any.

🎉 That's it, enjoy using Swetrix! Let us know if you find any bugs or have any feedback for us and join our Discord for latest updates!

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

v3.3.1

Warning

This release contains some breaking changes that require migrations, so please read these instructions carefully.

What changed:

🔥 Major updates

• Added native support for hostname tracking - now you can properly track multiple websites in a single project and see what domain the data is coming from using the Host panel.

🙂 Minor changes

• Improved live visitors tracking.
• Refactored dashboard and analytics pages to be more robust and faster.
• Added skeleton loader for project cards on the dashboard page.

🔧 Fixes

• (?) Fixed Minified React error #31 thrown when logging into account.

Upgrading to Swetrix v3.3.1 (from v3.3.0)

Important

You will need to perform a database migration. Please make sure you read these instructions through to the end to make sure you've updated properly and to avoid losing any data.

1. Run database migration scripts

Warning

Please make sure you always back up your data! Especially before migrating, to prevent data loss if something goes wrong.

In order to upgrade to Swetrix v3.3.1, 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/2025_01_09.js

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

After performing the migration, you can run docker compose restart and Swetrix should be good to go!

🎉 That's it, enjoy selfhosting Swetrix! Let us know if you find any bugs or have any feedback for us and join our Discord.

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

v3.3.0

Warning

This release contains some breaking changes that require migrations, so please read these instructions carefully.

What changed:

🔥 Major updates

• Add support for UTM Term & UTM Content metrics
• Add browser and OS version metrics
• Swetrix is now more memory efficient with lots of optimisations done for our Clickhouse and Redis usage
• Added support for region and city geolocation tracking. Swetrix now ships with a DB-IP geolocation database, you can also use your own .mmdb databases by setting a new IP_GEOLOCATION_DB_PATH variable
• Clickhouse logs are no longer removed by Swetrix and instead we strongly recommend that you tune Clickhouse with its config files. We include several configs for this, so read on to know how to enable them
• Removed API_ORIGINS environment variable. The Allowed origins setting on the project settings page should be used instead
• Removed SELFHOSTED environment variable
• Added IS_PRIMARY_NODE environment variable. For 99% of use cases there's no need to set up multiple API nodes, one node is capable of handling lots of traffic, so it's recommended to keep it at true.

🙂 Minor changes

• Redesigned notifications
• Displaying custom events metadata in session overview
• Added sorting for custom events and page-views metadata table
• Replaced blake3 session hashing with xxHash for better performance
• Removed always shown scrollbars on overflowing rows for dashboard panels
• Now you can go to user session by clicking on rows inside Live visitors dropdown
• Disable comparisons for This hour timebucket due to it's buggy behaviour

🔧 Fixes

• Session filters do not work properly when refreshing the page
• Fixed an issue when sometimes you could see TypeError: Cannot destructure property 'index' of 's[0]' as it is null errors thrown in dashboard
• Session chart is not working when account timezone is not set to UTC
• User flow chart did not work properly and did not display accurate data
• Errors tracked with Swetrix were displayed in dashboard with a delay for users with timezone not set at UTC
• Geolocation tracking was not working for users who had CLOUDFLARE_PROXY_ENABLED variable set to true
• Sharable link on project settings was set to swetrix.com

Upgrading to Swetrix v3.3.0 (from v3.2.x)

Important

You will need to perform a database migration. Please make sure you read these instructions through to the end to make sure you've updated properly and to avoid losing any data.

1. Added .env file; docker-compose.yml is now compose.yaml

We've taken a lot of feedback from the previous release into account and tried to make the self-hosted version of Swetrix easy to set up, upgrade and maintain. So some changes have been made to achieve this.

Before upgrading, you should back up your docker-compose.yml settings, as you'll need them later.

To upgrade your configuration files, do the following:

1. Go to the selfhosting repository and run the docker compose down command to switch off Swetrix.
2. Back up your docker-compose.yml settings somewhere else, as you will need to reuse them later on. Run git pull to download our latest config (if this command does not work, you can run git checkout -- . first, but make sure you have saved your config file, as this will undo your changes).
3. After you do a git pull, run the ./configure.sh script. It will prompt you to enter environment variables one at a time and will generate an .env file at the end. You can edit this .env file manually as well if required.
4. Run the docker compose up -d command. This will pull the latest Swetrix and Clickhouse releases. If you open your dashboard now, it will not work properly. This is expected as you still need to do a data migration to synchronise the new code with the database tables.

The new compose.yaml configuration also comes with several different Clickhouse configs from us to make Swetrix work more efficiently and faster. You can also create your own configs and add them to the compose file.

2. Run database migration scripts

Warning

Please make sure you always back up your data! Especially before migrating, to prevent data loss if something goes wrong.

In order to upgrade to Swetrix v3.3.0, you will need to run database migrations scripts. We assume that you've already followed the instructions above, so your compose.yaml file should already 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/2024_09_10.js
docker compose exec swetrix-api node migrations/clickhouse/2024_10_15.js
docker compose exec swetrix-api node migrations/clickhouse/2024_10_20.js
docker compose exec swetrix-api node migrations/clickhouse/2024_10_25.js
docker compose exec swetrix-api node migrations/clickhouse/2024_10_26.js
docker compose exec swetrix-api node migrations/clickhouse/2024_10_27.js
docker compose exec swetrix-api node migrations/clickhouse/2024_10_28.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2024_10_17.js

It will perform the migrations one at a time. If you don't see any Query ERROR messages written to your console, this indicates that the migrations went well and Swetrix v3.3.0 is ready to use. You should not run this script more than once.

After performing the migrations, you can run docker compose restart and Swetrix should be good to go!

🎉 That's it, enjoy selfhosting Swetrix! Let us know if you find any bugs or have any feedback for us and join our Discord.

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