Medama Analytics Self-Hosting Guide

Discover Medama Analytics, an open-source, self-hostable, privacy-focused comprehensive website analytics platform.

We explore its cookie-free JavaScript tracker, Go-based API server, React TypeScript dashboard, and SQLite-powered storage.

Learn key modules, algorithms, dependencies, and deployment strategies for Medama using Docker.

Equip yourself with best practices to run Medama Analytics securely on your modern infrastructure.

In this post, we explore its architecture, core modules, deployment options with Docker, key algorithms, and how to configure and run a fully open-source, efficient, GDPR-compliant analytics stack.

Project Overview: Medama Analytics

Looking for a privacy-first, self-hosted analytics solution? Medama Analytics combines a sub-1KB cookie-free tracker with a Go-based API and a React/Bun dashboard.

Why Medama Matters

• Ensure compliance with GDPR and privacy regulations through a cookie-free design.
• Benefit from a minimal (<1KB gzipped) tracker to reduce page load overhead.
• Self-hostable single-binary Go backend with lightweight SQLite databases.
• OpenAPI-based server enables easy integration and customization.

• The Medama Analytics Source Code

Medama doesn’t ship a single “root” LICENSE – each part is licensed separately, yet under Open Source Licenses:

• Core (the Go API) and Dashboard (the React app) are both under the Apache License 2.0 (see core/LICENSE and dashboard/LICENSE)
• Tracker (the <1 KB JS snippet) is under the MIT License (see tracker/LICENSE)

Module Descriptions

• Core: Go backend API managing data ingestion, processing, and storage using SQLite and DuckDB, with RESTful endpoints defined by OpenAPI.
• Dashboard: React TypeScript frontend offering real-time analytics visualization and intuitive data exploration via charts and tables.
• Tracker: Ultra-lightweight JavaScript snippet (<1KB gzipped) capturing events without cookies and sending data to the API.

Key Concepts and Algorithms

• Cookie-free analytics: leverage session identifiers and IP anonymization to protect user privacy.
• Data storage: combine SQLite for transactional operations and DuckDB for analytical queries, with managed migrations.
• OpenAPI-driven development: single source of truth for API schema, generating server and TypeScript client types.
• Compression & performance: integrate HTTP compression middleware and optimize payload sizes for minimal bandwidth.

Dependencies

For the most interested on the under the hood Medama tech:

• Go modules: Ogen, zerolog, sqlx, certmagic, duckdb, go-referrer-parser, go-timezone-country, go-useragent.
• JavaScript/TypeScript: React, Remix, Vite, @mantine/, @radix-ui/, bun, biome, esbuild.
• Tracker build: bun, terser, preprocess, brotli-size, gzip-size.

High-Level Overview - Medama Analytics includes:

• Languages & Structure: Go backend (/core), React TypeScript dashboard (/dashboard), pure JS tracker (/tracker).
• Dependencies: Go modules specified in go.mod; Node workspaces for dashboard and tracker managed via Bun and package.json.
• Configuration & Environment: environment variables (ANALYTICS_DATABASE_HOST, APP_DATABASE_HOST, PORT, LEVEL, DEMO_MODE, PROFILER) with defaults in Dockerfile and Fly.io config.
• Static Analysis: gofumpt and golangci-lint for Go; Biome for TS/JS linting; Taskfile automates formatting, linting, and testing.

Deployment: Medama Analytics

Medama provides a Dockerfile for multi-stage builds and a Fly.io configuration (fly.toml). For self-hosting, build and run via Docker:

docker build -t medama-analytics .
docker run -d --name medama \
  -p 8080:8080 \
  -e ANALYTICS_DATABASE_HOST=/app/data/me_analytics.db \
  -e APP_DATABASE_HOST=/app/data/me_app.db \
  -v "$PWD/data":/app/data \
  medama-analytics:latest

Docker Compose for Medama

sudo docker-compose up -d
#docker-compose -f medama_docker-compose.yml up -d
#sudo docker logs medama
#sudo docker stats medama

services:
  medama: #
    image: ghcr.io/medama-io/medama:latest #https://oss.medama.io/deployment/docker
    container_name: medama #https://oss.medama.io/introduction
    restart: unless-stopped
    environment:
      - LOGGER=pretty
    ports:
      - "8085:8080"
    volumes:
      - medama_data:/app/data
      #- ./data:/app/data
#     networks:
#       - nginx_nginx_default #for https

# networks:
#   nginx_nginx_default:
#     external: true  

volumes:
  medama_data:

I have tested Medama with the Container version v.0.5.2:

docker images | grep "ghcr.io/medama-io/medama" #https://github.com/medama-io/medama/pkgs/container/medama

Thanks to https://mariushosting.com/how-to-install-medama-on-your-synology-nas/

sudo docker-compose up -d
#docker-compose -f liwan_docker-compose.yml up -d

Go to localhost:8085 and enter admin/CHANGE_ME_ON_FIRST_LOGIN

sudo docker logs medama
#sudo docker stats medama

You will need https to access with these: admin/CHANGE_ME_ON_FIRST_LOGIN

As per the docs: The default login credentials are

Username: admin
Password: CHANGE_ME_ON_FIRST_LOGIN

To successfully login, you must either use localhost or a HTTPS connection.

Logging in via an unencrypted HTTP connection will not work.

For that, you can use NGINX as Proxy!

Services Explained:

• medama: runs the Go API server, handles tracker ingestion and serves the dashboard.

Configuration:

• Edit environment variables in Docker run or Compose to change DB paths, port, log level, demo mode, and profiling settings.

Conclusion

Medama Analytics is a robust, privacy-centric analytics solution for self-hosting enthusiasts.

For Selfhosting Medama, you will need aroudn ~250mb RAM, which should be fine for any small VPS.

We covered its architecture, modules, algorithms, and deployment patterns.

For further control, can potentially build the Medama container image by following these CLIs:

export DOCKER_BUILDKIT=1

# pick your version + commit (or leave as the defaults “development”)
        VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo development)
        COMMIT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo development)

docker build \
          --build-arg VERSION=${VERSION} \
          --build-arg COMMIT_SHA=${COMMIT_SHA} \
          -t medama:latest \
          .

If you are ready to alternatives include Matomo, Umami, Plausible, and GoatCounter for similar self-hosted analytics needs.

Latest Releases

• v0.5.2: Improved CI by enabling fail-fast on Edge concurrency groups for faster build failure feedback.
• v0.5.1: Upgraded DuckDB integration to enhance analytical query performance and compatibility.
• v0.5.0: Fixed mobile header link color in the dashboard for better UI consistency on smaller screens.
• v0.4.4: Reset date range state when navigating periods in the dashboard, improving user experience.

git log -1 --pretty=format:'%h %s (%ci)'
#f655f73 chore: upgrade dependencies (#161) (2025-04-21 07:51:16 +0000)

git describe --tags --abbrev=0
#v0.5.2

git tag --sort=-v:refname | head -n 5