Repository navigation
Epic 1: streamline installation for first-timers (Docker + macOS binary + homepage) #3137
Description
Aim
Clarify the user flow around installation/getting started, following up on work underway (for ex, #3066 #3089, #3110).
Why
Post- #3089 we'll still have four pages across two repos pointing to the same general step. (Install info at https://github.com/prometheus/prometheus/ is versioned and appears under Prometheus Server. Information in /docs is not versioned.)
| Doc | Live page | Source file | What it is |
|---|---|---|---|
| Overview | https://prometheus.io/docs/introduction/overview/ | https://github.com/prometheus/docs/blob/main/docs/introduction/overview.md | High-level intro, no operations/steps |
| First steps | https://prometheus.io/docs/introduction/first_steps/ | https://github.com/prometheus/docs/blob/main/docs/introduction/first_steps.md | Binary setup — "install, configure and monitor our first resource with Prometheus" |
| Getting started | https://prometheus.io/docs/prometheus/latest/getting_started/ | https://github.com/prometheus/prometheus/blob/main/docs/getting_started.md | "'Hello World'-style tutorial which shows how to install, configure, and use a simple Prometheus instance" |
| Installation | https://prometheus.io/docs/prometheus/latest/installation/ | https://github.com/prometheus/prometheus/blob/main/docs/installation.md | Lists the different ways to install Prometheus |
Suggestion: make a quick start based on the Docker option, being honest about its limits and clearer about its pros/cons
- Document that the one-line
docker runuses the baked-in sample config, that it cannot be edited for later steps, and state the recovery path explicitly (createprometheus.yml,docker rm -f, re-run with-vconfig mount + named data volume). Related: Documentation: missing examples with named docker volumes / no info about the right data-path (/prometheus) in container #2285, Documentation for docker volume for data storage #1879 - Document
host.docker.internal/ container networking for targets reachable from the container. Related: node exporter page needs info for non-localhost configuration #1980 - Document pros and cons:
- Docker pros: One command, zero setup (image ships a working default config); pinned & reproducible; Easy teardown w/
docker rm -f; matches real-world ops. - Docker cons: Abstraction layer hides the moving parts/config is inside the container; ghost-container traps.
- Binary pros: Zero abstraction (see the process, the flags, the config file, the TSDB directory); everything is a plain file; full control.
- Binary cons: Manual setup, some steps may not be necessary for a quick start. Also initially presented a Gatekeeper/notarization warning when I tried it the first time. Related: docs: Getting started guide could add mention of validating checksums #1946; see docs(first-steps): checksum verification and macOS first-run fixes #3138.
Also:
- Fix walkthrough gaps: the /query vs /metrics flow, what
{}in the result means, whatrate()and[1m]do, the graph needs a few minutes of data, frame the "Monitoring other targets" link. - Fix the "Next Page" flow so the page after the quick start is the natural next step (node exporter guide), not "Comparison to Alternatives".
- Add a short "how to read the graph" note: y-axis units (e.g. "1.80m"), stacked vs unstacked, point density at high resolution, gaps when a laptop sleeps, empty legend entries.
Activity
lasomethingsomething commentedon Oct 13, 2026
Epic 2: Provide a tour of the web UI
Aim
Explain what features do, step by step, to ease onboarding
Why
For a first-timer it isn't obvious what certain features provide and when/how to use them
TODOs
lasomethingsomething commentedon Oct 13, 2026
Epic 3 next-step guides (node exporter, OTel) work for Docker (or all?) users
Aim
Correct a suggested blocker for Docker (and other) users around node exporter and OpenTelemetry next-steps
Node exporter guide (guides/node-exporter)
host.docker.internal:9100as the target, and a "verify your targets are UP" step before querying. Related: node exporter page needs info for non-localhost configuration #1980OpenTelemetry guide (guides/opentelemetry)
--web.enable-otlp-receivercurrently assumes the binary). Corroborated by docs: Issue with "First steps with Prometheus" #3032.dice.rollsarrives asdice_rolls_total) and theotel_scope_*plumbing labels.last_over_time()for "current value" lookups on push-based data.lasomethingsomething commentedon Oct 13, 2026
Epic 4: content hygiene on the first-run path (comparison page, roadmap)
Aim
Update stale pages created from the project's early days; archive if appropriate.
Checklist
- [ ] Relates to tree test study at https://treetest.fajerski.name/s/promcon26; seeking more participants.
granman3 commentedon Oct 14, 2026
Hi! I'd like to take the macOS binary path section (extract/run commands with zsh wildcard handling, the Gatekeeper/notarization warning, and checksum validation, which would also close #1946). I'll walk through a fresh install on macOS (Apple Silicon) and open one PR covering all three items. Happy to split it if you'd prefer smaller PRs. Does that work?
docs(first-steps): checksum verification and macOS first-run fixes