Muon
GitHub Start for free
Home›Docs›Deploy›Docker

Deploy Muon with Docker Compose

Docker Compose is the fastest way to self-host Muon — backend, dashboard and PostgreSQL in one command.

How do I deploy Muon with Docker?

Clone the repo and run docker compose up -d. It starts the Muon backend, the Muon frontend and PostgreSQL — three services, one command.

Docker Compose is recommended for local testing, small teams, single-server deployments and migration from Umami. When you outgrow one box, the same images scale to Kubernetes without changing tools.

Before you start

Prerequisites

You only need two things installed on the host — your laptop or a single server:

  • Docker — the container runtime.
  • Docker Compose — bundled with recent Docker Desktop and Docker Engine as the docker compose subcommand.

No Rust toolchain, no Node.js and no separate database install are required — everything runs inside containers.

Quick start

Three commands to a running stack

Clone the repository, enter it, and bring the stack up in the background:

  bash
# clone the Muon repository
git clone https://github.com/runmuon/muon
# enter the project directory
cd muon
# start backend, frontend and PostgreSQL
docker compose up -d

Once the containers are healthy, open the dashboard in your browser:

  dashboard
http://localhost:3000

Port 3000 is the default frontend port. Create your account on first visit and you are ready to start collecting events.

What's inside

Services

The Compose file defines three services that work together.

Muon backend
Rust collector + API. Ingests events on the Umami-compatible /api/send endpoint and serves the dashboard API.
Muon frontend
React dashboard for reports, funnels, goals, browser health and Findings. Served on port 3000 by default.
PostgreSQL
Storage for events and configuration, persisted in a Docker volume so your data survives restarts and upgrades.
Send events

Point your tracker at Muon

Muon speaks the same tracking protocol as Umami, so the setup is a single script tag.

Drop the tracking script into your site's <head>, pointing src at your Muon host and setting your website's ID:

  html
<script
  defer
  src="http://localhost:3000/script.js"
  data-website-id="your-website-id"></script>

Events are delivered to the Umami-compatible /api/send endpoint on the backend. Because the wire format matches Umami, an existing Umami tracker keeps working — just change its src to your Muon host.

Good fit

Recommended for

  • Local testing — spin up the full product on your laptop in minutes.
  • Small teams — a single Compose stack is plenty for early traffic.
  • Single-server deployments — one VM, one command, your data stays with you.
  • Migration from Umami — Umami-compatible tracking plus an importer make the switch low-risk.

Need high availability, horizontal scaling or a managed database? Move to the Kubernetes deployment — the backend is stateless and scales horizontally behind PostgreSQL.

Where to go next

Next steps

FAQ

Questions, answered directly.

What do I need to run Muon?
Docker and Docker Compose installed on a single host. That is enough to run the Muon backend, the React dashboard and PostgreSQL locally or on one server.
What services run?
Three services: the Muon backend (Rust collector and API), the Muon frontend (React dashboard) and PostgreSQL for storage.
How do I upgrade?
Pull the latest images and re-run docker compose up -d. Compose recreates the backend and frontend containers while your PostgreSQL data volume is preserved.
Can I use my own Postgres?
Yes. Point the Muon backend at an external database by setting DATABASE_URL to your own PostgreSQL instance and removing the bundled postgres service.
How do I migrate from Umami?
Muon uses an Umami-compatible /api/send tracking endpoint, so existing trackers keep working. Historical data can be moved over with the Umami importer.
Open source · self-hosted

Run your own analytics tonight.

Clone it, docker compose up -d, and open the dashboard. When you outgrow one box, scale to Kubernetes with the same images.

Kubernetes deployment guide → View GitHub