Umami

Umami is a lightweight, privacy‑first web analytics platform written in modern JavaScript. It replaces heavy cloud services like Google Analytics with a self‑hosted solution that respects user data while delivering real‑time insights. The core of Umami is a Next.js front‑end that serves a single‑page application, coupled with an Express/Node.js API layer that exposes REST endpoints for event ingestion and reporting. The backend uses Prisma as an ORM to abstract database interactions, supporting MariaDB, MySQL, and PostgreSQL out of the box. This architecture keeps the stack minimal yet powerful, enabling developers to run Umami on any Linux server or container without additional dependencies.

Technical Stack & Architecture

• Front‑end: Next.js (React) with TypeScript, leveraging server‑side rendering for SEO and static generation for the public dashboard pages.
• Back‑end: Node.js 18+ with Express, exposing a JSON API for event tracking (/api/track) and analytics queries.
• Database: Prisma ORM supports MariaDB (≥10.5), MySQL (≥8.0), and PostgreSQL (≥12.14). The schema is intentionally simple—tables for visitors, sessions, events, and properties—yet fully ACID‑compliant.
• Containerization: Official Docker images are provided for each database variant, simplifying deployment with docker compose. The image is built on a lightweight Node base and exposes port 3000, ready for reverse proxy or direct routing.
• Deployment: No external services are required; a single database instance and the Node process constitute a complete stack. For scaling, horizontal deployment can be achieved by sharing the same database across multiple instances behind a load balancer.

Core Capabilities & APIs

Umami exposes two primary API surfaces:

1. Tracking Endpoint – A lightweight POST endpoint that accepts JSON payloads containing page URLs, referrers, user agents, and custom properties. The API is intentionally minimal to reduce network overhead; it responds with a 204 status, making it ideal for embedding in production sites.
2. Analytics API – Authenticated endpoints that return aggregated metrics such as pageviews, unique visitors, bounce rate, and custom event counts. These endpoints are documented in the public API reference and can be consumed by dashboards, CI pipelines, or third‑party tools.

Custom events are supported via the event field in the tracking payload, allowing developers to instrument arbitrary actions (e.g., button clicks, form submissions). Additionally, the platform offers webhooks for real‑time notifications on new sessions or event thresholds, enabling integration with messaging services or alerting systems.

Deployment & Infrastructure

Umami’s minimal footprint (≈ 70 MB for the Docker image) makes it suitable for edge deployments, VPS, or container orchestrators like Kubernetes. The single‑process design means you can run multiple instances behind a round‑robin load balancer, all pointing to the same database. For high‑availability, replicas of the database are recommended; Prisma supports connection pooling to mitigate latency spikes. The application is stateless, so scaling horizontally incurs negligible complexity.

Integration & Extensibility

While Umami ships with a complete UI, its extensibility lies in the API surface. Developers can:

• Embed the tracking script directly or via a tag manager, customizing event payloads.
• Consume analytics data programmatically to feed custom dashboards or reporting tools.
• Hook into webhooks for real‑time alerts or trigger external workflows (e.g., Slack notifications, GitHub Actions).
• Contribute to the open‑source codebase; the repository follows semantic versioning and has an active issue tracker, making it straightforward to propose feature extensions or database migrations.

Developer Experience

Configuration is handled via a single .env file, exposing only the DATABASE_URL. The documentation at umami.is/docs is concise yet comprehensive, covering API usage, event schema, and deployment nuances. The community is active on GitHub and Twitter, with rapid issue triage and frequent releases (monthly). The MIT license removes any commercial restrictions, allowing developers to embed Umami in proprietary projects without licensing overhead.

Use Cases

• Small‑to‑medium websites that require GDPR‑compliant analytics without third‑party cookies.
• Internal tooling dashboards where sensitive visitor data must remain on-premises.
• Edge‑first applications (e.g., JAMstack sites) that benefit from a lightweight, CDN‑friendly tracking script.
• Continuous integration pipelines that generate automated reports on site performance or event usage.

Advantages Over Alternatives

• Performance: The minimal tracking payload and server‑side rendering yield low latency, even on shared hosting.
• Privacy: No data is sent to external services; all logs stay within the operator’s control.
• Flexibility: The open‑source API and event schema allow bespoke instrumentation without waiting for feature releases.
• Cost: Zero licensing fees and a small Docker image reduce infrastructure costs compared to commercial analytics platforms.

In summary, Umami offers developers a clean, self‑hosted analytics stack that balances speed, privacy, and extensibility.