The operator’s manual. five minutes, honestly

Three commands. FlowMiner clones, builds, and comes up on localhost:3000. No external services, no account creation, no credit card.

$ git clone https://github.com/flowminer-stack/flowminer
$ cd flowminer && cp .env.example .env
$ docker compose up -d

[+] Running 6/6
 ✓ postgres    Healthy   12.3s
 ✓ redis       Healthy    8.1s
 ✓ backend     Healthy   38.7s
 ✓ worker      Started   39.1s
 ✓ beat        Started   39.4s
 ✓ frontend    Started   41.2s

$ open http://localhost:3000
$ █

From logged-in to a process map you actually trust. Use one of the sample logs that ship under docs/examples/ — no real data required.

1. Create a project

   Click New project on the sidebar. A project is just a container for logs, so the HR-onboarding traces stay separate from the invoicing ones.

2. Upload an event log

   Drop a CSV or XES file onto the upload panel. The column mapper auto-detects case_id, activity, and timestamp — confirm and click ingest. For OCEL 2.0, upload the .jsonocel directly.

   Sample logs: docs/examples/running-example.csv and docs/examples/sample-order-management.jsonocel in the repo — or grab them from the live demo.

3. Read the process map

   Click into the log. The Process tab is the default view — the discovered map, with frequency on every edge. Filter rare paths out, switch to performance-weighted edges to see where time goes, or highlight the critical path.

4. Explore variants and conformance

   The Analysis tab has every view you’d expect: variants, bottlenecks, rework, temporal profile, handoff network, log skeleton, conformance via token replay. Hit each one once so you know where it is.

5. Ask the AI

   Open the chat panel and ask “what are my worst bottlenecks?” — it runs get_bottlenecks() against the current log and answers with numbers that came from your data, not a hallucination. Every tool call is visible, so you can audit what it did.

   Requires an LLM provider — see MAN 04 · Connect an LLM. Two minutes with an Anthropic or OpenRouter key.

FlowMiner reads its config from .env at the repo root. The defaults work for a single-machine install; these are the keys worth actually looking at before you put it anywhere real.

There are a few dozen other knobs — rate-limit bands, Celery queues, Sentry DSN, SMTP — but you only need them when hardening a real deployment. backend/app/config.py has the full list; every field has an inline comment.

Ask AI is the chat panel that answers questions about a log. It needs a model. Pick one provider, drop the key into .env, restart the backend. All four below work out of the box.

FLOWMINER_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-6

FLOWMINER_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1

FLOWMINER_LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=anthropic/claude-haiku-4-5

FLOWMINER_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_MODEL=llama3.1:70b

No key at all? Leave FLOWMINER_LLM_PROVIDER unset. Every mining view still works; only the chat panel is disabled.

Once the default Compose stack feels too small, these are the knobs worth reaching for — in roughly the order most people reach for them.

A handful of things go wrong on fresh installs. These are the fixes 95% of people need.

Backend won’t start — database “flowminer” does not exist

The Postgres init ran before the backend mounted its volume. Bring the stack down and up once more: docker compose down && docker compose up -d. Alembic picks up from an empty database on first run.

Frontend loads but shows “Network error”

The SPA is looking for the API at the wrong origin. Set VITE_API_URL to your public backend URL and rebuild with docker compose build frontend.

Upload stalls on large files

The reverse proxy is capping request size. For Caddy, set request_body { max_size 500MB }. For Nginx, bump client_max_body_size. FlowMiner itself has no upload cap.

Ask AI says “no provider configured”

You haven’t set FLOWMINER_LLM_PROVIDER, or the API key is missing / wrong. Jump to MAN 04. Restart the backend after editing .env — env vars are read at boot, not on each request.

OCEL upload errors with “invalid jsonocel”

pm4py only reads OCEL 2.0. If your file is OCEL 1.0 (top-level ocel:events object), convert it first or regenerate from source.

Stuck on something that isn’t listed? Open an issue on GitHub with your docker compose logs backend output — the maintainers read every one.