From 5670dd852da425dd1f162f48741c027910e49cc9 Mon Sep 17 00:00:00 2001
From: granman <45244251+granman3@users.noreply.github.com>
Date: Tue, 13 Oct 2026 19:03:18 -0600
Subject: [PATCH] docs(first-steps): checksum verification and macOS first-run
 fixes

- Explain how to verify the download's SHA256 checksum on Linux, macOS
  and Windows before extracting it (closes #1946).
- Use `cd prometheus-*/` so the wildcard only matches the extracted
  directory; `cd prometheus-*` fails in bash and zsh when the tarball is
  in the same directory.
- Note where browser downloads land and what `no matches found` means.
- Add a NOTE on the macOS Gatekeeper block for browser-downloaded
  binaries and the two ways to allow them.

Part of #3137.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: granman <45244251+granman3@users.noreply.github.com>
---
 docs/introduction/first_steps.md | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/introduction/first_steps.md b/docs/introduction/first_steps.md
index 6a202146b..5c4700dfe 100644
--- a/docs/introduction/first_steps.md
+++ b/docs/introduction/first_steps.md
@@ -8,14 +8,36 @@ Welcome to Prometheus! Prometheus is a monitoring platform that collects metrics
 
 ## Downloading Prometheus
 
-[Download the latest release](/download) of Prometheus for your platform, then
-extract it:
+[Download the latest release](/download) of Prometheus for your platform.
+Browsers usually save it to your `Downloads` folder, so run the following
+commands from there (for example, `cd ~/Downloads`).
+
+Before extracting the archive, check that it wasn't corrupted or tampered with:
+compute its SHA256 checksum and compare it with the checksum listed for that file
+on the [download page](/download).
+
+```language-bash
+# Linux
+sha256sum prometheus-*.tar.gz
+# macOS
+shasum -a 256 prometheus-*.tar.gz
+```
+
+On Windows, run `Get-FileHash prometheus-*.zip -Algorithm SHA256` in PowerShell.
+If the checksums don't match, delete the file and download it again.
+
+Then extract the archive and change into the extracted directory:
 
 ```language-bash
 tar xvfz prometheus-*.tar.gz
-cd prometheus-*
+cd prometheus-*/
 ```
 
+The trailing `/` makes the wildcard match only the extracted directory. Without
+it, `prometheus-*` also matches the `.tar.gz` file and `cd` fails with
+`too many arguments` (bash) or `string not in pwd` (zsh). If your shell reports
+`no matches found`, you're not in the directory that contains the download.
+
 The Prometheus server is a single binary called `prometheus` (or `prometheus.exe` on Microsoft Windows). We can run the binary and see help on its options by passing the `--help` flag.
 
 ```language-bash
@@ -27,6 +49,8 @@ The Prometheus monitoring server
 . . .
 ```
 
+NOTE: On macOS, binaries downloaded with a web browser are quarantined. Because the Prometheus binaries aren't notarized by Apple, macOS blocks `prometheus` the first time you run it, and the shell reports that the process was killed (for example, `zsh: killed`). After verifying the checksum, either click **Allow Anyway** next to "prometheus" in **System Settings > Privacy & Security** and run the command again, or run `xattr -dr com.apple.quarantine .` inside the extracted directory. Downloads made with `curl` or `wget` aren't quarantined.
+
 Before starting Prometheus, let's configure it.
 
 ## Configuring Prometheus