Skip to main content

Feature: Analytics Setup (Umami)

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

Status: Draft (Definition Incomplete)​

Goal: Add privacy-friendly analytics to track website usage without cookies or GDPR concerns.

Last Updated: 2026-01-17

Prerequisites: None (can be done anytime)

Priority: Future (requires account setup decision)

Overview​

Add analytics to understand how users interact with the DevContainer Toolbox website. Using Umami instead of Google Analytics because:

  • No cookies = no cookie banner needed
  • GDPR compliant out of the box
  • Lightweight (~2KB script)
  • Privacy-respecting (aligns with sovereignty mission)
  • You own the data

Why Umami Over Google Analytics​

FeatureUmamiGoogle Analytics
CookiesNoneRequired
GDPRCompliant by defaultRequires consent banner
Script size~2KB~45KB
Data ownershipYou own itGoogle owns it
PrivacyPrivacy-firstTracking-first
CostFree (self-hosted) or $9/moFree (but you're the product)

Definition Tasks (To Complete Before Implementation)​

  • Decide: Umami Cloud ($9/mo) or self-hosted (free)?
  • If self-hosted: where to host? (Docker on existing server?)
  • Create Umami account/instance
  • Get tracking script/site ID
  • Decide what metrics matter most
  • Consider: should analytics be mentioned on the site? (transparency)

Hosting Options​

Cost: $9/month (Hobby plan) URL: https://umami.is/

Pros:

  • No infrastructure to manage
  • Automatic updates
  • Reliable uptime

Cons:

  • Monthly cost
  • Data on Umami's servers (but privacy-respecting)

Option B: Self-Hosted​

Cost: Free (but need a server) Requirements: Docker, PostgreSQL or MySQL

Pros:

  • Free
  • Full data ownership
  • Can customize

Cons:

  • Need to maintain server
  • Updates are manual
  • Need monitoring

Option C: Self-Hosted on Existing Infrastructure​

If urbalurba-infrastructure already has hosting, Umami could run there.

Pros:

  • Uses existing resources
  • Integrated with other services

Cons:

  • Dependency on infrastructure repo
  • May complicate deployment

Proposed Implementation​

Docusaurus Plugin​

Use @dipakparmar/docusaurus-plugin-umami:

npm install @dipakparmar/docusaurus-plugin-umami
// docusaurus.config.ts
plugins: [
  [
    '@dipakparmar/docusaurus-plugin-umami',
    {
      websiteID: 'your-website-id',
      analyticsDomain: 'analytics.example.com', // or cloud.umami.is
      dataHostURL: 'https://analytics.example.com',
      // Only active in production
    },
  ],
],

Key Metrics to Track​

MetricWhy
Page viewsWhich docs are most used
Tool page visitsWhich tools are popular
Blog post readsContent engagement
ReferrersHow users find us
CountriesGeographic distribution
DevicesMobile vs desktop

Proposed Phases (Draft)​

Phase 1: Account Setup​

  • Decide on hosting option
  • Create Umami account/instance
  • Get website ID and tracking domain

Phase 2: Plugin Installation​

  • Install @dipakparmar/docusaurus-plugin-umami
  • Configure with website ID
  • Test locally (should not track in dev)

Phase 3: Deployment & Verification​

  • Deploy to production
  • Verify tracking works
  • Check dashboard shows data

Phase 4: Documentation​

  • Document analytics setup for contributors
  • (Optional) Add privacy note to website footer

Acceptance Criteria (Draft)​

  • Analytics tracking active in production
  • No cookies or consent banner required
  • Dashboard accessible to view metrics
  • Only tracks production (not localhost)
  • Documented in contributor docs

Files to Modify (Estimated)​

  • website/package.json - Add Umami plugin
  • website/docusaurus.config.ts - Plugin configuration
  • website/docs/contributors/website.md - Document analytics

Open Questions​

  1. Umami Cloud or self-hosted?
  2. Who should have access to the analytics dashboard?
  3. Should we mention analytics in the site footer? (transparency)
  4. What's the budget for hosted services?
  5. If self-hosted, where does it run?

Cost Comparison​

OptionMonthly CostAnnual Cost
Umami Cloud (Hobby)$9$108
Self-hosted$0 + server costsVaries
Google Analytics$0$0 (but privacy cost)

Reference​