docs: fix glibc troubleshooting -- generic version, devcontainer guidance, fix broken code block

Copilot · danielmeppiel · web-flow · commit 52541eaa10ca · 2026-03-27T06:08:34.000Z
Agent-Logs-Url: https://github.com/microsoft/apm/sessions/aa1bd54d-ae2c-4ff4-b699-24ff933c8bec Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md
@@ -145,17 +145,25 @@ mkdir -p ~/bin
 # then install the binary to ~/bin/apm and add ~/bin to PATH
 ```
 
-### Binary install fails on older Linux (devcontainers, Debian Bookworm)
+### Binary install fails on older Linux (devcontainers, Debian-based images)
 
-On systems with glibc older than 2.39 (e.g., Debian Bookworm with glibc 2.36), the
-pre-built binary may fail to run. The installer automatically detects this and falls
-back to installing APM via `pip install --user apm-cli`.
+On systems with a glibc version older than what the pre-built binary requires, the
+binary will fail to run. This commonly affects Debian Bookworm-based devcontainers
+(glibc 2.36) since the binary is built on Ubuntu 24.04 (glibc 2.39). The installer
+automatically detects incompatible glibc versions and falls back to
+`pip install --user apm-cli`.
 
 This installs the `apm` command into your user `bin` directory (commonly `~/.local/bin`).
 If `apm` is not found after installation, ensure that this directory is on your `PATH`.
 
+**Recommended fix for devcontainers:** switch your base image from `bookworm` to
+`trixie` (e.g., `mcr.microsoft.com/devcontainers/universal:24-trixie`), which ships
+glibc 2.40+ and runs the pre-built binary directly.
+
 If you prefer to install via pip directly:
 
+```bash
+pip install --user apm-cli
 ```
 
 ### Authentication errors when installing packages
