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

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)

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

1. 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!!

1. 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

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!

🎉 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!