Building a Self-Hosted 'Static Site Analytics & Privacy-First Tracking' Infrastructure on a VPS with Umami and ClickHouse

Introduction: The Paradigm Shift in Web Analytics

For over a decade, Google Analytics has been the default choice for tracking website traffic. However, the modern web ecosystem is undergoing a massive shift. Driven by stricter data privacy regulations like GDPR and CCPA, growing user awareness, and the widespread adoption of ad-blockers, traditional tracking methods are losing their efficacy. Furthermore, heavy JavaScript tracking scripts degrade the performance of static sites, contradicting the core benefits of using frameworks like Hugo, Gatsby, or Next.js.

For businesses that prioritize data sovereignty, user privacy, and site performance, the solution lies in self-hosting. By combining Umami—a lightweight, privacy-focused open-source analytics tool—with ClickHouse—a fast, column-oriented database management system—you can build a robust, enterprise-grade analytics infrastructure on a single Virtual Private Server (VPS). This guide provides a comprehensive blueprint for architecting this system.

Why Choose Umami and ClickHouse for Static Sites?

Static sites demand infrastructure that mirrors their efficiency. Standard analytics tools often rely on relational databases like PostgreSQL or MySQL. While sufficient for low-traffic sites, these databases struggle under high-volume analytical queries (OLAP). Here is why the Umami-ClickHouse stack stands out:

• Privacy-First Compliance: Umami does not collect personally identifiable information (PII). It anonymizes IP addresses and does not use cookies, making it compliant with GDPR out of the box without requiring intrusive cookie banners.
• Unparalleled Performance: ClickHouse organizes data by columns rather than rows. This allows it to process billions of rows of tracking data per second, executing analytical queries in milliseconds while using minimal disk space due to advanced data compression.
• Bypassing Ad-Blockers: Because the analytics script and data collection endpoint are hosted on your own domain/VPS, they are not caught by standard third-party ad-blocker lists, ensuring highly accurate data collection.
• Data Sovereignty: Your business retains 100% ownership of its data. No third-party tech giants can mine your user behavior insights for advertising purposes.

Architectural Blueprint

Before diving into the implementation, it is crucial to understand how data flows through this self-hosted ecosystem:

1. The Client: The user visits your static site, triggering a lightweight, open-source script (less than 2KB) hosted on your domain.
2. The Reverse Proxy: Nginx routes incoming tracking requests securely over HTTPS to the Umami application.
3. The Application Layer: Umami processes the raw telemetry data without extracting sensitive user identifiers.
4. The Database Layer: Umami writes the structured events directly into ClickHouse for optimized columnar storage and lightning-fast retrieval.

Note: While Umami historically used PostgreSQL or MySQL, its native support for ClickHouse transforms it into a highly scalable solution capable of handling millions of monthly pageviews on a modest VPS.

Step-by-Step Implementation Guide

1. VPS Provisioning and Initial Setup

To ensure smooth operation, we recommend a VPS with at least 2 vCPUs and 4GB of RAM, running Ubuntu 22.04 LTS or 24.04 LTS. ClickHouse is highly efficient with CPU and memory but requires adequate resources for heavy concurrent queries.

First, update your system packages and install necessary dependencies like Docker and Docker Compose:

sudo apt update && sudo apt upgrade -y
sudo apt install docker.io docker-compose-v2 curl git -y

2. Configuring ClickHouse and Umami via Docker Compose

Using Docker Compose is the cleanest method to orchestrate our containers. Create a dedicated directory and define your architecture in a docker-compose.yml file:

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: umami-clickhouse
    environment:
      - CLICKHOUSE_DB=umami
      - CLICKHOUSE_USER=umami_user
      - CLICKHOUSE_PASSWORD=your_secure_password
    volumes:
      - ch_data:/var/lib/clickhouse
    ports:
      - "127.0.0.1:8123:8123"
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    restart: always

  umami:
    image: ghcr.io/umami-software/umami:clickhouse-latest
    container_name: umami-app
    environment:
      - DATABASE_URL=clickhouse://umami_user:your_secure_password@clickhouse:8123/umami
      - APP_SECRET=your_random_long_string_for_encryption
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      - clickhouse
    restart: always

volumes:
  ch_data:

Run docker compose up -d to initialize both services. Umami will automatically run its database migrations against ClickHouse upon first boot.

3. Securing the System with Nginx and Let's Encrypt

To serve the tracking script securely and access the dashboard, expose Umami behind an Nginx reverse proxy secured with an SSL certificate.

Configure Nginx to route traffic from your subdomain (e.g., analytics.yourcompany.com) to the internal Umami container running on port 3000. Ensure you pass the correct headers to preserve client IP metadata for geolocation mapping within Umami:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;

Deploy Let's Encrypt using Certbot to achieve automated, zero-cost SSL renewals. This guarantees that all tracking telemetry is encrypted in transit.

Optimizing Static Site Integration

Once your infrastructure is active, log into your Umami dashboard, create a new website asset, and retrieve your tracking code. Insert the generated script tag into the element of your static site generator's base template.

To drastically minimize the probability of being blocked by aggressive tracking filters, you can use Nginx to proxy the script file itself, masking the endpoint as a standard static asset belonging to your main application domain.

Conclusion: Future-Proofing Corporate Web Analytics

By migrating from generic, third-party analytics scripts to a self-hosted Umami and ClickHouse pipeline, your organization achieves a rare trifecta in modern web development: maximum performance, absolute data compliance, and infrastructural cost control. Your static site remains incredibly lean, your visitors' privacy is strictly respected, and your business intelligence reporting retains its accuracy in an increasingly ad-blocked digital landscape.