Added a basic umami setup for visitor statistics

Author: dutow

app/views/layouts/application.html.slim

@@ -27,6 +27,9 @@ html data-theme="light"
     = stylesheet_link_tag "application", "data-turbo-track": "reload"
     = javascript_importmap_tags
     script[src="https://kit.fontawesome.com/92fb6aa8ba.js"]
+    - if ENV["UMAMI_WEBSITE_ID"].present?
+      - umami_host = ENV["UMAMI_HOST"].presence || "https://umami.hackorum.dev"
+      script[async defer data-website-id=ENV["UMAMI_WEBSITE_ID"] src="#{umami_host}/script.js"]
   body
     - if user_signed_in? && current_user.username.blank?
       .global-warning

deploy/.env.example

@@ -29,6 +29,18 @@ GOOGLE_REDIRECT_URI=https://hackorum.example.com/auth/google_oauth2/callback
 # Hostname for Caddy (update deploy/Caddyfile too)
 APP_HOST=hackorum.example.com
 
+# Umami analytics (self-hosted)
+# Generate secrets with: openssl rand -hex 32
+UMAMI_DB=umami
+UMAMI_DB_USER=umami
+UMAMI_DB_PASSWORD=change-me
+UMAMI_DATABASE_URL=postgresql://umami:change-me@db:5432/umami
+UMAMI_APP_SECRET=change-me
+UMAMI_HASH_SALT=change-me
+UMAMI_WEBSITE_ID=
+# Optional override; defaults to https://umami.hackorum.dev
+# UMAMI_HOST=https://umami.hackorum.dev
+
 # Mail configuration via Mailgun
 # Sign up at https://mailgun.com and verify your domain (use subdomain mg.example.com)
 # Get credentials from Mailgun dashboard → Sending → Domain settings → SMTP credentials

deploy/Caddyfile.example

@@ -8,3 +8,10 @@ hackorum.example.com {
     output stdout
   }
 }
+
+umami.hackorum.dev {
+  reverse_proxy umami:3000
+  log {
+    output stdout
+  }
+}

deploy/README.md

@@ -5,6 +5,7 @@ This is a minimal, single-host setup for running Hackorum on a VPS (e.g., Hetzne
 - IMAP runner (continuous)
 - Postgres with WAL archiving to a local volume
 - Caddy for TLS / reverse proxy
+- Umami analytics (self-hosted)
 - Autoheal watchdog to restart unhealthy containers
 - Local base backups + WAL retention scripts (no external storage)
 
@@ -28,8 +29,14 @@ This is a minimal, single-host setup for running Hackorum on a VPS (e.g., Hetzne
 
 3) Update Caddyfile domain:
    - Edit `deploy/Caddyfile` and replace `hackorum.example.com` and contact email.
+   - Ensure the Umami host is set to `umami.hackorum.dev` (see `deploy/Caddyfile.example`).
 
-4) Build and start:
+4) Configure Umami analytics:
+   - Set `UMAMI_APP_SECRET` and `UMAMI_HASH_SALT` in `deploy/.env`.
+   - Set `UMAMI_DB_USER` and `UMAMI_DB_PASSWORD` for the dedicated Umami database user.
+   - Confirm `UMAMI_DATABASE_URL` points at the shared Postgres service.
+
+5) Build and start:
    ```bash
    cd deploy
    docker compose up -d --build
@@ -39,19 +46,45 @@ This is a minimal, single-host setup for running Hackorum on a VPS (e.g., Hetzne
    - `imap_worker`: continuous IMAP ingest
    - `db`: Postgres 18 with WAL archiving to `/var/lib/postgresql/wal-archive`
    - `caddy`: TLS + reverse proxy on :80/:443
+   - `umami`: self-hosted analytics UI/API on port 3000 (internal)
    - `autoheal`: restarts containers whose healthchecks fail
 
-5) Verify:
+6) Verify:
    - Browse to your domain; or `curl -f http://localhost:3000/up` from the host (`docker compose exec web ...` inside the network).
 
 ## Observability
 - Query stats: pg_stat_statements is preloaded via the Postgres config and created on first init via `/docker-entrypoint-initdb.d/01_pg_stat_statements.sql`. For existing databases, run `CREATE EXTENSION IF NOT EXISTS pg_stat_statements;` once. PgHero is available at `/pghero` for signed-in admin users.
 - Request-level profiling: rack-mini-profiler is available; in production it renders only for signed-in admin users.
 
+## Analytics (Umami, self-hosted)
+Umami runs as a separate service and uses the same Postgres container (recommended: separate database).
+
+Initialization:
+- Fresh install: the init script creates the Umami database (`UMAMI_DB`, default `umami`) on first Postgres boot.
+- Existing database: create it once manually (adjust user/db if needed):
+  ```bash
+  docker compose exec db psql -U postgres -d postgres -c "CREATE ROLE umami LOGIN PASSWORD 'change-me';"
+  docker compose exec db psql -U postgres -d postgres -c "CREATE DATABASE umami OWNER umami;"
+  ```
+
+Access:
+- Add a dedicated hostname in Caddy (example in `deploy/Caddyfile.example`).
+- Visit `https://umami.hackorum.dev` and log in (default `admin` / `umami`, then change the password).
+- Create a website in Umami and copy the `website_id` into `UMAMI_WEBSITE_ID` in `deploy/.env`.
+
 ## Environment variables (deploy/.env)
 - `SECRET_KEY_BASE` (required)
 - `DATABASE_URL` (defaults to local Postgres via env interpolation)
 - `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` (for the db container)
+- Umami:
+  - `UMAMI_DB` (database name for init script; default `umami`)
+  - `UMAMI_DB_USER` (dedicated Umami database user)
+  - `UMAMI_DB_PASSWORD` (dedicated Umami database password)
+  - `UMAMI_APP_SECRET` (required, 32+ random hex chars recommended)
+  - `UMAMI_HASH_SALT` (required, 32+ random hex chars recommended)
+  - `UMAMI_DATABASE_URL` (defaults to local Postgres with `UMAMI_DB`)
+  - `UMAMI_WEBSITE_ID` (required for client-side tracking)
+  - `UMAMI_HOST` (optional override; defaults to https://umami.hackorum.dev)
 - IMAP:
   - `IMAP_USERNAME`, `IMAP_PASSWORD`, `IMAP_MAILBOX_LABEL`
   - Optional: `IMAP_HOST`, `IMAP_PORT`, `IMAP_SSL`

deploy/docker-compose.yml

@@ -8,6 +8,9 @@ services:
       POSTGRES_USER: ${POSTGRES_USER:-postgres}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
       POSTGRES_DB: ${POSTGRES_DB:-hackorum}
+      UMAMI_DB: ${UMAMI_DB:-umami}
+      UMAMI_DB_USER: ${UMAMI_DB_USER:-umami}
+      UMAMI_DB_PASSWORD: ${UMAMI_DB_PASSWORD:-umami}
     volumes:
       # Postgres 18+ stores data under /var/lib/postgresql/<major>/main
       - pgdata:/var/lib/postgresql
@@ -66,6 +69,22 @@ services:
     labels:
       autoheal: "true"
 
+  umami:
+    image: umami/umami:postgresql-latest
+    env_file: .env
+    environment:
+      DATABASE_URL: ${UMAMI_DATABASE_URL:-postgresql://${UMAMI_DB_USER:-umami}:${UMAMI_DB_PASSWORD:-umami}@db:5432/${UMAMI_DB:-umami}}
+      APP_SECRET: ${UMAMI_APP_SECRET}
+      HASH_SALT: ${UMAMI_HASH_SALT}
+    depends_on:
+      db:
+        condition: service_healthy
+    expose:
+      - "3000"
+    restart: unless-stopped
+    labels:
+      autoheal: "true"
+
   imap_worker:
     build: ..
     command: ["bundle", "exec", "ruby", "script/imap_idle.rb"]

deploy/postgres/init/02_create_umami_db.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+UMAMI_DB="${UMAMI_DB:-umami}"
+UMAMI_DB_USER="${UMAMI_DB_USER:-umami}"
+UMAMI_DB_PASSWORD="${UMAMI_DB_PASSWORD:-umami}"
+
+psql -v ON_ERROR_STOP=1 \
+  -v UMAMI_DB="$UMAMI_DB" \
+  -v UMAMI_DB_USER="$UMAMI_DB_USER" \
+  -v UMAMI_DB_PASSWORD="$UMAMI_DB_PASSWORD" \
+  --username "$POSTGRES_USER" \
+  --dbname "postgres" <<'EOSQL'
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = :'UMAMI_DB_USER') THEN
+    EXECUTE format('CREATE ROLE %I LOGIN PASSWORD %L', :'UMAMI_DB_USER', :'UMAMI_DB_PASSWORD');
+  END IF;
+END
+$$;
+
+SELECT format('CREATE DATABASE %I OWNER %I', :'UMAMI_DB', :'UMAMI_DB_USER')
+WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = :'UMAMI_DB')\gexec
+EOSQL