Introduction: The Paradigm Shift in Web Analytics

In the contemporary digital landscape, data privacy is no longer an afterthought—it is a regulatory and ethical imperative. With the stringent enforcement of GDPR, CCPA, and the gradual phasing out of third-party cookies by major browsers, traditional analytics platforms like Google Analytics face mounting scrutiny. Businesses are increasingly trapped between the need for actionable user insights and the legal complications of compliance consent banners.

Fortunately, a powerful alternative has emerged: cookie-less, privacy-first web analytics. By tracking user behavior without harvesting personally identifiable information (PII) or storing persistent identifiers on client devices, organizations can bypass intrusive cookie consent banners entirely. This blog post provides an enterprise-ready, technical blueprint for deploying Umami Analytics backed by a ClickHouse database on a self-hosted Virtual Private Server (VPS). This combination offers unparalleled speed, absolute data ownership, and compliance by design.

---

Why Umami and ClickHouse? The Ultimate Data Synergy

Before diving into the deployment architecture, it is essential to understand why the combination of Umami and ClickHouse represents a paradigm shift for modern engineering and marketing teams.

Umami: The Lightweight, Privacy-First Frontend

Umami is an open-source, self-hosted web analytics solution written in Next.js. Unlike heavy analytics scripts that degrade website performance, Umami’s tracking script is incredibly lightweight (under 6 KB) and executes asynchronously. Key advantages include:

No Cookies: Umami does not use cookies, local storage, or persistent tracking mechanisms. It generates an anonymized hash based on the visitor's IP address, User-Agent, and hostname, ensuring compliance without compromising UX.
Beautiful, Intuitive UI: It distills complex metrics into a clean, single-page dashboard accessible to both technical and non-technical stakeholders.
Bypass Ad-Blockers: When self-hosted on your own domain or subdomain, Umami is significantly less likely to be blocked by standard privacy extensions, yielding more accurate traffic data.

ClickHouse: The Enterprise-Grade Analytical Engine

While Umami natively supports relational databases like PostgreSQL and MySQL, scaling a high-traffic website on these transactional systems often leads to performance bottlenecks. Enter ClickHouse, an open-source, column-oriented online analytical processing (OLAP) database management system.

In a standard transactional database, data is stored in rows, making aggregations across millions of records painfully slow. ClickHouse stores data in columns, allowing it to process billions of rows and gigabytes of data per second. By offloading Umami’s analytical queries to ClickHouse, your system gains the capacity to handle millions of monthly pageviews on a modest, cost-effective VPS without breaking a sweat.

---

System Architecture and Prerequisites

To successfully implement this architecture, we will utilize Docker and Docker Compose for container orchestration, ensuring isolated, reproducible environments. Before proceeding, ensure your infrastructure meets the following baseline requirements:

A Linux VPS: A minimum of 2 vCPUs and 4GB of RAM is highly recommended. ClickHouse is highly optimized but requires sufficient memory for heavy analytical queries.
Operating System: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS.
Domain Name: A dedicated domain or subdomain (e.g., analytics.yourcompany.com) with A/AAAA records pointed to your VPS IP address.
Software Installed: Docker Engine (v20.10+) and Docker Compose (v2.0+).

---

Step-by-Step Deployment Guide

Step 1: Preparing the Server Environment

First, connect to your VPS via SSH and create a dedicated directory structure to house your configuration files and persistent data volumes:

mkdir -p ~/umami-clickhouse/clickhouse-data
mkdir -p ~/umami-clickhouse/clickhouse-config
cd ~/umami-clickhouse

Step 2: Configuring ClickHouse

ClickHouse requires specific user configurations to grant Umami secure access. Create a user configuration file at ./clickhouse-config/users.xml to define database credentials and resource allocations:


    
        
            YourSecurePasswordHere
            
                ::/0
            
            default
            default

Step 3: Orchestrating Services via Docker Compose

Create a docker-compose.yml file in the root of your project directory. This configuration defines the Umami application instance, the ClickHouse database engine, a relational database (PostgreSQL) used briefly for Umami's structural metadata, and an Nginx reverse proxy with automated SSL certificate provisioning via Let's Encrypt.

Note: Ensure you replace placeholders like database passwords and domain names with your actual secure strings before executing the stack.

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: umami-clickhouse
    volumes:
      - ./clickhouse-data:/var/lib/clickhouse
      - ./clickhouse-config/users.xml:/etc/clickhouse-server/users.d/users.xml
    environment:
      - CLICKHOUSE_DB=umami
      - CLICKHOUSE_USER=umami_user
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    restart: always
    ports:
      - "8123:8123"

  db:
    image: postgres:15-alpine
    container_name: umami-postgres
    environment:
      POSTGRES_DB: umami_metadata
      POSTGRES_USER: umami_admin
      POSTGRES_PASSWORD: MetaSecurePassword
    volumes:
      - ./pg-data:/var/lib/postgresql/data
    restart: always

  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami-app
    environment:
      - DATABASE_URL=postgresql://umami_admin:MetaSecurePassword@db:5432/umami_metadata
      - CLICKHOUSE_URL=http://umami_user:YourSecurePasswordHere@clickhouse:8123/umami
      - APP_SECRET=A_Long_Random_String_For_Encryption_Security
    ports:
      - "3000:3000"
    depends_on:
      - db
      - clickhouse
    restart: always

Step 4: Launching the Stack

With configurations in place, initialize the multi-container architecture by running the following command in your terminal:

docker compose up -d

Verify that all containers are functioning optimally by checking the runtime logs: docker compose logs -f. Umami automatically detects the ClickHouse connection and runs internal migrations to set up the necessary analytical tables.

---

Optimizing for Production: Reverse Proxy and Security

Exposing port 3000 directly to the web is highly discouraged. To secure production data, implement an Nginx reverse proxy paired with Certbot to handle SSL termination. Configure Nginx to route external traffic securely:

server {
    listen 80;
    server_name analytics.yourcompany.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name analytics.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/[analytics.yourcompany.com/fullchain.pem](https://analytics.yourcompany.com/fullchain.pem);
    ssl_certificate_key /etc/letsencrypt/live/[analytics.yourcompany.com/privkey.pem](https://analytics.yourcompany.com/privkey.pem);

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

Integrating the Cookie-Less Tracker into Your Website

Once your Umami instance is operational via HTTPS, log into the dashboard using the default credentials (admin / umami), and immediately update your password. Navigate to the settings pane, add your target website, and copy the auto-generated tracking script.

Insert the script into the section of your web application:

Because Umami operates entirely without cookies, you can safely remove your intrusive analytics consent banner for users, maximizing data capture accuracy while providing a friction-free, professional browsing experience.

---

Conclusion

Deploying Umami alongside ClickHouse on a self-hosted VPS strikes the perfect balance between robust data insights, blistering performance, and strict privacy compliance. By taking ownership of your infrastructure, you safeguard your users' digital rights, reduce reliance on third-party tech monopolies, and future-proof your business against evolving data privacy legislation. The era of cookie-based tracking is ending; building your self-hosted analytical engine ensures you stay ahead of the curve.

Building a Privacy-First, Cookie-Less Web Analytics System: Umami with ClickHouse on a Self-Hosted VPS