umami-setup.md

Optional Analytics Setup

Overview

Analytics are optional and disabled by default. This guide shows how to enable self-hosted Umami analytics to track:

1. Website visits (automatic pageviews)
2. Run starts (custom event)
3. Run completions (custom event)

Umami is open source, privacy-first (no cookies), and you control all data on your own infrastructure.

Note: The production example at devkeys.app has analytics enabled to demonstrate the feature. Your self-hosted instance will have analytics disabled by default.

Deployment Setup

1. Deploy Umami

Using your preferred container orchestration platform (Dokploy, Coolify, Docker Compose, etc.):

1. Create New Project → Docker Compose
2. Name it "umami-analytics"
3. Paste this docker-compose configuration:

services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET}
    depends_on:
      db:
        condition: service_healthy
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  umami-db-data:

4. Set Environment Variables:

   • Copy env.example to .env and update the values
   • UMAMI_APP_SECRET = generate random 32-char string
   • VITE_ANALYTICS_URL = your analytics domain (e.g., https://analytics.domain/script.js)
   • VITE_ANALYTICS_WEBSITE_ID = your website ID from Umami dashboard

5. Configure Domain: Set up subdomain like analytics.domain

6. Enable HTTPS: Most platforms auto-generate SSL via Let's Encrypt

7. Deploy and wait for health checks to pass

8. Initial Setup:

   • Visit https://analytics.domain
   • Default login: admin / umami
   • Change password immediately
   • Go to Settings → Websites → Add Website
   • Enter your main site domain: domain
   • Copy the Website ID from the tracking code

2. Deploy Main App

1. Create New Project → Git Repository
2. Connect your GitHub repo
3. Platform will auto-detect Vite/React
4. Build Settings:
   • Build Command: pnpm install && pnpm build:wasm && pnpm build:web
   • Publish Directory: apps/web/dist
5. Configure domain: domain
6. Deploy