Add Umami analytics integration with runtime website ID injection

- Add Umami service to docker-compose with PostgreSQL backend
- Add analytics tracking proxy via nginx (/analytics/script.js, /analytics/api/send)
- Add WEBSITE_ID and UMAMI_PORT configuration to setup.sh
- Add entrypoint scripts to www/web containers for runtime ID injection
- Add analytics script tags to all HTML files
- Dashboard accessible via direct port (default 3006)

Author: nickprotop

cloud/deploy/Dockerfile.web

@@ -65,5 +65,14 @@ EXPOSE 80
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD curl -sf http://localhost:80/ || exit 1
 
-# nginx runs as non-root by default in this config
-CMD ["nginx", "-g", "daemon off;"]
+# Create entrypoint script to inject WEBSITE_ID at runtime
+RUN printf '#!/bin/sh\n\
+set -e\n\
+if [ -n "$WEBSITE_ID" ]; then\n\
+  sed -i "s/data-website-id=\"[^\"]*\"/data-website-id=\"$WEBSITE_ID\"/g" \\\n\
+    /usr/share/nginx/html/index.html\n\
+fi\n\
+exec nginx -g "daemon off;"\n\
+' > /entrypoint.sh && chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

cloud/deploy/Dockerfile.www

@@ -25,4 +25,14 @@ EXPOSE 80
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD curl -sf http://localhost:80/ || exit 1
 
-CMD ["nginx", "-g", "daemon off;"]
+# Create entrypoint script to inject WEBSITE_ID at runtime
+RUN printf '#!/bin/sh\n\
+set -e\n\
+if [ -n "$WEBSITE_ID" ]; then\n\
+  find /usr/share/nginx/html -name "*.html" -exec \\\n\
+    sed -i "s/data-website-id=\"[^\"]*\"/data-website-id=\"$WEBSITE_ID\"/g" {} \\;\n\
+fi\n\
+exec nginx -g "daemon off;"\n\
+' > /entrypoint.sh && chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

cloud/deploy/config.sample.json

@@ -174,5 +174,9 @@
   },
   "superAdmin": {
     "emails": ["admin@example.com"]
+  },
+  "analytics": {
+    "umamiSecret": "YOUR_UMAMI_APP_SECRET_32_PLUS_CHARS",
+    "websiteId": "YOUR_UMAMI_WEBSITE_ID"
   }
 }

cloud/deploy/deploy.sh

@@ -174,6 +174,16 @@ else
     print_success "nginx configured without SSL"
 fi
 
+# ============================================================================
+# Step 1.6: Show analytics config status
+# ============================================================================
+WEBSITE_ID=$(grep -oP '^WEBSITE_ID=\K.*' "$SCRIPT_DIR/.env" 2>/dev/null || echo "")
+if [ -n "$WEBSITE_ID" ]; then
+    print_info "Analytics Website ID: ${WEBSITE_ID:0:8}..."
+else
+    print_info "Analytics Website ID: not configured (run setup.sh to set)"
+fi
+
 # ============================================================================
 
 # Step 2: Pull base images
@@ -207,6 +217,15 @@ docker compose stop api web www nginx
 print_step "Starting containers..."
 docker compose up -d
 
+# Step 5.1: Ensure umami database exists (for analytics)
+print_step "Ensuring umami database exists..."
+if docker exec lrmcloud-postgres psql -U "${POSTGRES_USER:-lrm}" -d postgres -lqt | cut -d \| -f 1 | grep -qw umami; then
+    print_info "Umami database already exists"
+else
+    docker exec lrmcloud-postgres psql -U "${POSTGRES_USER:-lrm}" -d postgres -c "CREATE DATABASE umami;"
+    print_success "Created umami database"
+fi
+
 # Step 5.5: Restart nginx to ensure it picks up config changes + refresh DNS
 print_step "Restarting nginx..."
 docker compose up -d nginx

cloud/deploy/docker-compose.yml

@@ -18,6 +18,7 @@ services:
       - api
       - web
       - www
+      - umami
     healthcheck:
       test: ["CMD", "wget", "-q", "--spider", "http://localhost/health"]
       interval: 30s
@@ -56,6 +57,8 @@ services:
     # No ports exposed - proxied by nginx
     volumes:
       - ./data/logs/web:/var/log/nginx
+    environment:
+      - WEBSITE_ID=${WEBSITE_ID:-}
     healthcheck:
       test: ["CMD", "curl", "-sf", "http://localhost:80/health"]
       interval: 30s
@@ -75,6 +78,8 @@ services:
     # No ports exposed - proxied by nginx
     volumes:
       - ./data/logs/www:/var/log/nginx
+    environment:
+      - WEBSITE_ID=${WEBSITE_ID:-}
     healthcheck:
       test: ["CMD", "curl", "-sf", "http://localhost:80/health"]
       interval: 30s
@@ -130,3 +135,23 @@ services:
       timeout: 20s
       retries: 3
 
+  # ==========================================================================
+  # Umami Analytics
+  # ==========================================================================
+  umami:
+    image: ghcr.io/umami-software/umami:postgresql-latest
+    container_name: lrmcloud-umami
+    restart: unless-stopped
+    environment:
+      - DATABASE_URL=postgresql://${POSTGRES_USER:-lrm}:${POSTGRES_PASSWORD}@lrmcloud-postgres:5432/umami
+      - DATABASE_TYPE=postgresql
+      - APP_SECRET=${UMAMI_SECRET}
+    depends_on:
+      - postgres
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:3000/api/heartbeat"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+

cloud/deploy/init-db.sql

@@ -6,3 +6,6 @@ CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
 
 -- Grant privileges (database and user created by POSTGRES_DB/POSTGRES_USER env vars)
 -- Additional setup can be added here as needed
+
+-- Umami analytics database
+CREATE DATABASE umami;

cloud/deploy/nginx/nginx.conf.template

@@ -52,6 +52,7 @@ http {
     # Rate limiting zones
     limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;
     limit_req_zone $binary_remote_addr zone=api:10m rate=100r/s;
+    limit_req_zone $binary_remote_addr zone=analytics:10m rate=10r/s;
 
     # Upstream servers
     upstream api {
@@ -69,6 +70,11 @@ http {
         keepalive 8;
     }
 
+    upstream umami {
+        server lrmcloud-umami:3000;
+        keepalive 8;
+    }
+
     # =========================================================================
     # Security Headers
     # =========================================================================
@@ -198,6 +204,33 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
         }
 
+        # =====================================================
+        # Analytics Tracking (Umami) - /analytics/*
+        # Dashboard accessible via direct port (see setup.sh)
+        # =====================================================
+
+        # Tracking script
+        location = /analytics/script.js {
+            proxy_pass http://umami/script.js;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            expires 1d;
+            add_header Cache-Control "public";
+        }
+
+        # Tracking API endpoint
+        location = /analytics/api/send {
+            limit_req zone=analytics burst=20 nodelay;
+            limit_req_status 429;
+
+            proxy_pass http://umami/api/send;
+            proxy_http_version 1.1;
+            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;
+        }
+
         # =====================================================
         # Static Site / Landing Page (/)
         # =====================================================
@@ -340,6 +373,33 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
         }
 
+        # =====================================================
+        # Analytics Tracking (Umami) - /analytics/*
+        # Dashboard accessible via direct port (see setup.sh)
+        # =====================================================
+
+        # Tracking script
+        location = /analytics/script.js {
+            proxy_pass http://umami/script.js;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            expires 1d;
+            add_header Cache-Control "public";
+        }
+
+        # Tracking API endpoint
+        location = /analytics/api/send {
+            limit_req zone=analytics burst=20 nodelay;
+            limit_req_status 429;
+
+            proxy_pass http://umami/api/send;
+            proxy_http_version 1.1;
+            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;
+        }
+
         # =====================================================
         # Static Site / Landing Page (/)
         # =====================================================

cloud/deploy/setup.sh

@@ -97,6 +97,7 @@ CURRENT_POSTGRES_PORT=$(env_get 'POSTGRES_PORT' '5432')
 CURRENT_REDIS_PORT=$(env_get 'REDIS_PORT' '6379')
 CURRENT_MINIO_PORT=$(env_get 'MINIO_PORT' '9000')
 CURRENT_MINIO_CONSOLE=$(env_get 'MINIO_CONSOLE' '9001')
+CURRENT_UMAMI_PORT=$(env_get 'UMAMI_PORT' '')
 CURRENT_MINIO_USER=$(env_get 'MINIO_USER' 'lrmcloud')
 CURRENT_MINIO_PASSWORD=$(env_get 'MINIO_PASSWORD' '')
 
@@ -120,6 +121,8 @@ OLD_MINIO_PASSWORD="$CURRENT_MINIO_PASSWORD"
 CURRENT_JWT=$(config_get '.auth.jwtSecret' '')
 CURRENT_ENCRYPTION=$(config_get '.encryption.tokenKey' '')
 CURRENT_API_KEY_SECRET=$(config_get '.apiKeyMasterSecret' '')
+CURRENT_UMAMI_SECRET=$(config_get '.analytics.umamiSecret' '')
+CURRENT_WEBSITE_ID=$(config_get '.analytics.websiteId' '')
 
 CURRENT_MAIL_BACKEND=$(config_get '.mail.backend' 'smtp')
 CURRENT_MAIL_HOST=$(config_get '.mail.host' 'localhost')
@@ -210,6 +213,26 @@ MINIO_PORT=${MINIO_PORT:-$CURRENT_MINIO_PORT}
 read -p "MinIO Console Port (0=internal only) [$CURRENT_MINIO_CONSOLE]: " MINIO_CONSOLE
 MINIO_CONSOLE=${MINIO_CONSOLE:-$CURRENT_MINIO_CONSOLE}
 
+# Umami Analytics Dashboard Port
+if [ -n "$CURRENT_UMAMI_PORT" ]; then
+    CURRENT_UMAMI_ENABLED="y"
+    UMAMI_DEFAULT="Y/n"
+else
+    CURRENT_UMAMI_ENABLED="n"
+    UMAMI_DEFAULT="y/N"
+fi
+print_info "Umami dashboard requires direct port access (tracking works via main site)"
+read -p "Expose Umami dashboard port? [$UMAMI_DEFAULT]: " ENABLE_UMAMI
+ENABLE_UMAMI=${ENABLE_UMAMI:-$CURRENT_UMAMI_ENABLED}
+
+if [ "$ENABLE_UMAMI" = "y" ] || [ "$ENABLE_UMAMI" = "Y" ]; then
+    DEFAULT_UMAMI_PORT=${CURRENT_UMAMI_PORT:-3006}
+    read -p "Umami Direct Port [$DEFAULT_UMAMI_PORT]: " UMAMI_PORT
+    UMAMI_PORT=${UMAMI_PORT:-$DEFAULT_UMAMI_PORT}
+else
+    UMAMI_PORT=""
+fi
+
 read -p "Environment [$CURRENT_ENV]: " ENVIRONMENT
 ENVIRONMENT=${ENVIRONMENT:-$CURRENT_ENV}
 
@@ -420,6 +443,7 @@ DEFAULT_JWT_SECRET=${CURRENT_JWT:-$(generate_password)$(generate_password)}
 DEFAULT_ENCRYPTION_KEY=${CURRENT_ENCRYPTION:-$(generate_key)}
 DEFAULT_API_KEY_SECRET=${CURRENT_API_KEY_SECRET:-$(generate_password)$(generate_password)}
 DEFAULT_MINIO_PASSWORD=${CURRENT_MINIO_PASSWORD:-$(generate_password)}
+DEFAULT_UMAMI_SECRET=${CURRENT_UMAMI_SECRET:-$(generate_password)}
 
 # Prompt for PostgreSQL password
 if [ -n "$CURRENT_DB_PASSWORD" ]; then
@@ -475,6 +499,20 @@ else
 fi
 API_KEY_SECRET=${INPUT_API_KEY_SECRET:-$DEFAULT_API_KEY_SECRET}
 
+# Prompt for Umami analytics secret
+if [ -n "$CURRENT_UMAMI_SECRET" ]; then
+    print_info "Umami secret exists (hidden)"
+    read -p "Umami Secret [keep existing]: " INPUT_UMAMI_SECRET
+else
+    read -p "Umami Secret [$DEFAULT_UMAMI_SECRET]: " INPUT_UMAMI_SECRET
+fi
+UMAMI_SECRET=${INPUT_UMAMI_SECRET:-$DEFAULT_UMAMI_SECRET}
+
+# Prompt for Analytics Website ID
+print_info "Website ID is obtained from Umami dashboard after creating a website"
+read -p "Analytics Website ID [${CURRENT_WEBSITE_ID:-skip for now}]: " INPUT_WEBSITE_ID
+WEBSITE_ID=${INPUT_WEBSITE_ID:-$CURRENT_WEBSITE_ID}
+
 # ============================================================================
 # GitHub OAuth Configuration (optional)
 # ============================================================================
@@ -626,6 +664,10 @@ NEW_CONFIG=$(cat <<EOF
     "enterpriseTranslationChars": ${CURRENT_ENTERPRISE_TRANSLATION_CHARS},
     "enterpriseOtherChars": ${CURRENT_ENTERPRISE_OTHER_CHARS},
     "maxKeysPerProject": ${CURRENT_MAX_KEYS}
+  },
+  "analytics": {
+    "umamiSecret": "${UMAMI_SECRET}",
+    "websiteId": "${WEBSITE_ID}"
   }
 }
 EOF
@@ -678,6 +720,11 @@ REDIS_PASSWORD=${REDIS_PASSWORD}
 MINIO_USER=lrmcloud
 MINIO_PASSWORD=${MINIO_PASSWORD}
 
+# Analytics
+UMAMI_SECRET=${UMAMI_SECRET}
+WEBSITE_ID=${WEBSITE_ID}
+UMAMI_PORT=${UMAMI_PORT}
+
 # Environment
 ENVIRONMENT=${ENVIRONMENT}
 EOF
@@ -814,6 +861,16 @@ elif [ -n "$MINIO_CONSOLE" ] && [ "$MINIO_CONSOLE" != "0" ]; then
 EOF
 fi
 
+# Add Umami port if direct access enabled
+if [ -n "$UMAMI_PORT" ] && [ "$UMAMI_PORT" != "0" ]; then
+    cat >> "$OVERRIDE_FILE" <<EOF
+
+  umami:
+    ports:
+      - "${UMAMI_PORT}:3000"
+EOF
+fi
+
 print_success "Created docker-compose.override.yml"
 
 # ============================================================================
@@ -924,6 +981,14 @@ until docker exec lrmcloud-postgres pg_isready -U lrm -d lrmcloud &> /dev/null;
 done
 print_success "PostgreSQL is ready"
 
+# Ensure umami database exists (for analytics)
+if docker exec lrmcloud-postgres psql -U lrm -d postgres -lqt | cut -d \| -f 1 | grep -qw umami; then
+    print_info "Umami database already exists"
+else
+    docker exec lrmcloud-postgres psql -U lrm -d postgres -c "CREATE DATABASE umami;"
+    print_success "Created umami database"
+fi
+
 # Update PostgreSQL password if changed
 if [ -n "$OLD_POSTGRES_PASSWORD" ] && [ "$POSTGRES_PASSWORD" != "$OLD_POSTGRES_PASSWORD" ]; then
     print_step "Updating PostgreSQL password..."
@@ -1004,6 +1069,11 @@ if [ -n "$MINIO_CONSOLE" ] && [ "$MINIO_CONSOLE" != "0" ]; then
 else
     echo "  • MinIO Console: (internal only)"
 fi
+if [ -n "$UMAMI_PORT" ] && [ "$UMAMI_PORT" != "0" ]; then
+    echo "  • Analytics:     http://localhost:${UMAMI_PORT}"
+else
+    echo "  • Analytics:     (internal only)"
+fi
 echo ""
 echo "Configuration: $CONFIG_FILE"
 echo ""

cloud/src/LrmCloud.Web/wwwroot/index.html

@@ -36,6 +36,9 @@
     <link rel="stylesheet" href="css/app.css?v=__BUILD_VERSION__" />
     <link rel="icon" type="image/png" href="favicon.png" />
     <link rel="apple-touch-icon" href="icon-192.png" />
+
+    <!-- Analytics -->
+    <script defer src="/analytics/script.js" data-website-id="lrm-cloud" data-host-url="/analytics"></script>
 </head>
 
 <body>

cloud/src/www/docs/cloud.html

@@ -494,6 +494,9 @@
             }
         }
     </style>
+
+    <!-- Analytics -->
+    <script defer src="/analytics/script.js" data-website-id="lrm-cloud" data-host-url="/analytics"></script>
 </head>
 <body>
     <!-- Header -->