DOCSEARCHbyAlgolia
Submit Docs

Medama Documentation

repository·main·Indexed 20 days ago

https://github.com/medama-io/medama

An open-source, privacy-focused, and self-hostable website analytics platform. Medama provides cookie-free tracking via a lightweight JavaScript tracker (<1KB) and real-time insights through an OpenAPI-based server. It utilizes SQLite for application data and DuckDB for analytics, supporting low-resource deployments on VMs with as little as 256MB of memory.

Tokens
8.5K
Snippets
31
Records
38
Agent score
69%

What's inside Medama

  1. Overview of the Medama Tracker

    main
    The Medama Tracker is a lightweight JavaScript library used to power Medama analytics. It is designed to be extremely small and optimized for modern web compression (gzip and brotli) to minimize impact on page load performance.

  2. Overview of Medama Analytics

    main

    Medama Analytics is an open-source, self-hostable, and cookie-free website analytics platform. It is designed to prioritize user privacy by using a lightweight tracker (<1KB) that does not use cookies, IP addresses, or other identifiers, making it compliant with GDPR and PECR.

    Key capabilities include:

    • Real-Time Analytics: Instant monitoring of website performance and user interactions.
    • Privacy-First Design: No cookies or PII (Personally Identifiable Information) collected.
    • Easy Integration: Uses an OpenAPI-based server for integration with dashboards.
    • Low Resource Requirements: Can be deployed as a single binary on VMs with as little as 256MB of memory.

  4. Set up the Medama Dashboard for development

    main

    To develop the Medama Dashboard locally, you must first install the necessary repository tools using mise from the repository root, then install dependencies using bun, and finally start the development server from the dashboard directory.

    # From the repository root
mise install

# From the dashboard directory
cd dashboard
bun install
mise run dev

  5. Set up the Medama Core development environment

    main

    To develop on the Medama backend API service, ensure your environment meets the following requirements:

    1. Go Version: Use the specific Go version defined in the repository's root mise.toml.
    2. CGO Support: You must have gcc installed, as CGO is required for the project.
    3. Tooling: Install the necessary repository tools by running mise install from the repository root.
    4. Linting & Formatting: Configure your IDE to use gofumpt and golangci-lint for automatic code formatting and linting.
    5. Dependencies: Run go mod download to fetch required Go modules.

  7. Use Demo Mode

    main
    The --demo flag enables a restricted mode intended for demonstrations or read-only environments. In this mode, the server blocks all state-changing HTTP methods (POST, PATCH, DELETE) for all routes, except for the login endpoint, ensuring the underlying data remains unchanged.

  8. Enable Debug Profiling

    main

    To profile the running Medama server, use the --profiler flag. This enables the standard Go pprof endpoints, allowing you to inspect CPU profiles, heap, goroutines, and traces via HTTP.

    Available endpoints:

    • /debug/pprof/ (Index)
    • /debug/pprof/cmdline
    • /debug/pprof/profile
    • /debug/pprof/symbol
    • /debug/pprof/trace

  9. Enable Automatic SSL (AutoSSL)

    main

    Medama can automatically manage SSL certificates using Certmagic. When the --autossl flag is provided with a domain name:

    1. The server must be able to listen on ports 80 and 443.
    2. The domain must be publicly accessible and resolve to the server's IP.
    3. The server will automatically handle ACME challenges.
    4. All incoming HTTP requests will be redirected to HTTPS.

    You can optionally provide an email via --autosslemail for certificate notifications.

  10. Configure Playwright for @medama/tracker E2E tests

    main

    The @medama/tracker package uses Playwright for end-to-end testing. The configuration is environment-aware, adjusting behavior based on whether it is running in a Continuous Integration (CI) environment (detected via the CI environment variable).

    Key Test Settings

    • Test Directory: Tests are located in ./tests.
    • Timeouts: Individual test timeout is set to 20,000ms. The globalTimeout is set to 5 minutes on CI.
    • Parallelism: Tests run in fullyParallel mode. On CI, workers is restricted to 1 to maintain determinism for shared tracker/core servers.
    • Retries & Failures: On CI, tests will retry once (retries: 1) and the build will fail after 5 failures (maxFailures: 5).
    • CI Safety: forbidOnly is enabled on CI to prevent accidental test.only commits from passing.

    Browser Projects

    The test suite supports the following browser configurations:

    • chromium (Desktop Chrome)
    • firefox (Desktop Firefox)
    • webkit (Desktop Safari)
    • Microsoft Edge (using msedge channel)
    • Google Chrome (using chrome channel)

    Web Server Setup

    To run tests, the following local servers are automatically managed:

    1. Frontend/App Server: Started via bun run e2e:serve on port 3000.
    2. Core Server: Started via go run ./cmd start on port 8080 from the ../core directory. It is configured with debug logging and specific CORS origins (http://localhost:8080,http://localhost:5173).
    // Example of the configuration structure used in @medama/tracker
module.exports = defineConfig({
  testDir: './tests',
  timeout: 20_000,
  fullyParallel: true,
  use: {
    baseURL: 'http://localhost:3000',
    actionTimeout: 10_000,
    navigationTimeout: 10_000,
    trace: 'on-first-retry',
  },
  // ... projects and webServer definitions
});

  11. Configure Analytics Database host

    main

    The analytics database (typically DuckDB) can be configured via environment variables. By default, it uses a local DuckDB file.

    • ANALYTICS_DATABASE_HOST: The host or file path for the analytics database. (Default: ./me_analytics.db).

    Use NewAnalyticsDBConfig(true) to load this from the environment.

    // Load AnalyticsDBConfig from environment variables
analyticsDBConfig, err := NewAnalyticsDBConfig(true)

  12. Configure React Router SSR settings for the Dashboard

    main

    The Medama dashboard uses react-router for routing. You can control whether Server-Side Rendering (SSR) is enabled by setting the ssr property in the react-router.config.ts file. In the current configuration, SSR is disabled (ssr: false).

    import type { Config } from '@react-router/dev/config';

export default {
	ssr: false,
} satisfies Config;