Getting Started¶

Try Micromegas locally with Docker — no build, no dev environment.

Prerequisites¶

Docker with Compose v2 (v2.23.1+; bundled with current Docker Desktop, Rancher Desktop and recent Docker Engine). Check with docker compose version; if it is older, see Troubleshooting

1. Start Micromegas¶

Option A: clone-free¶

Fetch the compose file and start it, without cloning the repo:

curl -O https://raw.githubusercontent.com/madesroches/micromegas/main/docker/docker-compose.monolith.yaml
docker compose -f docker-compose.monolith.yaml up

Option B: from a clone¶

git clone https://github.com/madesroches/micromegas.git
cd micromegas
docker compose -f docker/docker-compose.monolith.yaml up

From a clone you can also use python3 docker/start_monolith_docker.py, which runs the same compose file in the background under its own compose project, micromegas-monolith, waits until the stack is ready, and prints the URLs to open. Pass --pull to fetch the latest image, --follow to tail the logs, and --down (with --volumes to also wipe the data) to remove the stack. Its containers and volumes are separate from a stack started with raw docker compose, so use the same method to stop it.

Either way, Docker pulls marcantoinedesroches/micromegas-monolith:latest and starts PostgreSQL plus a single monolith process running all roles (ingestion, analytics, web, maintenance). Data is stored in Docker volumes (Postgres data + a file-backed object store), so it persists across restarts but is easy to wipe (see Stopping / cleaning up).

Compose file contents

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: micromegas
      POSTGRES_PASSWORD: micromegas
      POSTGRES_DB: micromegas
    configs:
      - source: pg_init
        target: /docker-entrypoint-initdb.d/init-databases.sql
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U micromegas"]
      interval: 5s
      timeout: 5s
      retries: 5

  micromegas:
    image: marcantoinedesroches/micromegas-monolith:latest
    depends_on:
      postgres:
        condition: service_healthy
    command:
      - "--roles"
      - "all"
      - "--ingestion-listen-addr"
      - "0.0.0.0:9000"
      - "--frontend-dir"
      - "/app/frontend"
      - "--disable-auth"
    ports:
      - "9000:9000"
      - "50051:50051"
      - "3000:3000"
    environment:
      MICROMEGAS_SQL_CONNECTION_STRING: "postgres://micromegas:micromegas@postgres:5432/micromegas"
      MICROMEGAS_APP_SQL_CONNECTION_STRING: "postgres://micromegas:micromegas@postgres:5432/micromegas_app"
      MICROMEGAS_TELEMETRY_URL: "http://micromegas:9000"
      MICROMEGAS_FLUSH_PERIOD: "5"
      MICROMEGAS_OBJECT_STORE_URI: "file:///data"
      MICROMEGAS_WEB_CORS_ORIGIN: "http://localhost:3000"
      MICROMEGAS_BASE_PATH: "/"
    volumes:
      - lake:/data

configs:
  pg_init:
    content: |
      CREATE DATABASE micromegas_app;

volumes:
  pgdata:
  lake:

2. Open the web app¶

Once the containers are up, open http://localhost:3000. This is the analytics web app — a notebook-style UI for querying and visualizing the data in your Micromegas instance. Since the monolith ingests its own telemetry (see below), you can immediately open a notebook and query its self-telemetry.

3. (Optional) Run a query from Python¶

pip install micromegas

import datetime
import micromegas

# Connects to grpc://localhost:50051 by default — matches the compose
# file's FlightSQL port, so no configuration is needed locally.
client = micromegas.connect()

now = datetime.datetime.now(datetime.timezone.utc)
begin = now - datetime.timedelta(minutes=5)
end = now

sql = """
    SELECT time, process_id, level, target, msg
    FROM log_entries
    ORDER BY time DESC
    LIMIT 10;
"""

df = client.query(sql, begin, end)
print(df)

The monolith ingests its own traces and logs by default, so this query returns Micromegas's own self-telemetry rather than an empty table. Rows only appear after the first sink flush (MICROMEGAS_FLUSH_PERIOD, 5s in the compose file) and the maintenance role's continuous materialization of the global view (a ~1s cron) — so give it a couple of seconds after startup before you expect to see results.

Querying from outside Docker

The Python client's MICROMEGAS_ANALYTICS_URI environment variable can override the FlightSQL endpoint the CLI/client connects to — useful if you're running the query from a different host or container.

What you just ran¶

This setup is for evaluation, not production:

--disable-auth — no authentication on ingestion, FlightSQL, or the web app
A file-backed object store (file:///data) instead of S3/GCS/Azure
A single process running every role, with no isolation or horizontal scaling
Data lives in Docker volumes that are easy to delete (see below)

Not for production

For a real deployment, see Authentication to secure your instance and Monolith Deployment for configuration options, or split into per-role services for horizontal scale-out.

Stopping / cleaning up¶

If you started the stack with the script, stop it with the script (it uses the compose project micromegas-monolith, which raw docker compose ... down does not touch):

# Stop the containers (keeps data)
python3 docker/start_monolith_docker.py --down

# Stop and delete all data (Postgres + object store volumes)
python3 docker/start_monolith_docker.py --down --volumes

If you started it with docker compose ... up:

# Stop the containers (keeps data)
docker compose -f docker-compose.monolith.yaml down

# Stop and delete all data (Postgres + object store volumes)
docker compose -f docker-compose.monolith.yaml down -v

Next Steps¶

Query Guide - Learn how to query your observability data
Architecture Overview - Understand the system design
Unreal Engine Integration - Add observability to your Unreal Engine games
Instrument Your Application - Start collecting telemetry from your own applications

Building from source or contributing code? See the Build Guide.

Troubleshooting¶

Common Issues¶

Port already in use : The compose file binds 3000 (web app), 9000 (ingestion), and 50051 (FlightSQL) on the host. Stop whatever else is using those ports, or edit the ports: mappings in the compose file.

Image pull fails or hangs : Make sure Docker can reach Docker Hub, and that you're signed in if your organization requires it (docker login).

configs.pg_init Additional property content is not allowed : Your Docker Compose is older than v2.23.1 and does not support inline config content. Check your version with docker compose version (use docker compose, not the legacy docker-compose), then upgrade Docker Desktop, Rancher Desktop (with the dockerd/moby engine) or the docker-compose-plugin package.

If you can't upgrade, replace the inline config with a local file. Create `init-databases.sql` next to the compose file, containing `CREATE DATABASE micromegas_app;`. Then delete the top-level `configs:` block and the `configs:` entry of the `postgres` service, and add this line to that service's `volumes:`:

```yaml
      - ./init-databases.sql:/docker-entrypoint-initdb.d/init-databases.sql:ro
```

The init script only runs on an empty database, so run `docker compose -f docker-compose.monolith.yaml down -v` first if a `pgdata` volume already exists.

Empty query results : Expected for the first few seconds after startup — the sample query returns Micromegas's own self-telemetry, but rows only appear after the first sink flush (~5s) and the next maintenance materialization cycle (~1s cron). Wait a couple of seconds and re-run the query.

Getting Help¶

If you encounter issues:

Check the container logs: docker compose -f docker-compose.monolith.yaml logs
Create an issue on GitHub with details about your setup