README instructions to run docs-builder

[ketkee-aryamane]

Context: I was trying to run docs-builder locally by following the README. I have set up the Docker account, but when I run the cmd
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \ ghcr.io/elastic/docs-builder:edge, I get the following error. What is this access I am missing?

error::Program               :: System.UnauthorizedAccessException: Access to the path '/app/elastic' is denied.
 ---> System.IO.IOException: Permission denied
   --- End of inner exception stack trace ---
   at System.IO.FileSystem.CreateParentsAndDirectory(String, UnixFileMode) + 0x291
   at System.IO.FileSystem.CreateDirectory(String, UnixFileMode) + 0xad
   at System.IO.Directory.CreateDirectory(String) + 0x32
   at Documentation.Builder.Cli.CheckForUpdatesFilter.<GetLatestVersion>d__4.MoveNext() + 0x276
--- End of stack trace from previous location ---
   at Documentation.Builder.Cli.CheckForUpdatesFilter.<InvokeAsync>d__2.MoveNext() + 0x22f
--- End of stack trace from previous location ---
   at Elastic.Documentation.Tooling.Filters.CatchExceptionFilter.<InvokeAsync>d__2.MoveNext() + 0x16a
--- End of stack trace from previous location ---
   at Elastic.Documentation.Tooling.Filters.StopwatchFilter.<InvokeAsync>d__2.MoveNext() + 0x177
--- End of stack trace from previous location ---
   at ConsoleAppFramework.ConsoleApp.<RunWithFilterAsync>d__37.MoveNext() + 0xf5```

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

Following the README's docker run -v "./.git:/app/.git" … instructions crashed docs-builder with System.UnauthorizedAccessException: Access to the path '/app/elastic' is denied (thrown from the update-check filter), and the README itself was the source of that broken command.

Findings

• The broken README command is gone. PR #1781 (commit 4e484fdf, 2025-08-26) rewrote the README and removed the docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" ghcr.io/elastic/docs-builder:edge block entirely. The current README documents native-binary install and the docs-builder / docs-builder serve commands instead (README.md:L37-L83).
• Root cause fixed — the /app/elastic write. The crash came from the update check resolving its state directory relative to the container CWD (/app) when LocalApplicationData was empty. PR #3012 (commit a5c24489, 2026-04-02, "Fix ApplicationData path collision with workspace root in Docker/CI containers") makes Paths.GetApplicationFolder() fall back to Path.GetTempPath() in exactly that Docker/CI case, so it no longer tries to create /app/elastic (src/Elastic.Documentation.Tooling/Paths.cs:153-166).
• The old CheckForUpdatesFilter is now CheckForUpdatesMiddleware (renamed in PR #3202, commit 0d6115b8, 2026-05-07). State is written under per-user ApplicationData via a scoped filesystem, not the workspace (src/tooling/docs-builder/Middleware/CheckForUpdatesMiddleware.cs:18-19).
• The check can no longer crash a successful command. The middleware now (a) skips entirely when the CI env var is set (CheckForUpdatesMiddleware.cs:27-28) and (b) wraps the whole update check in a try/catch that logs at debug level — "a network failure here must never break the command that just succeeded" (CheckForUpdatesMiddleware.cs:38-42). Even if a write failed today it would be swallowed, not surfaced as an unhandled exception.

Verdict

Done

Both halves of this issue are resolved in current main. The README no longer ships the docker run invocation that produced the error (PR #1781), and the underlying defect — the update check writing to a non-writable /app/elastic path inside the container — was fixed by the ApplicationData fallback in PR #3012, then further hardened by the CI-skip and best-effort try/catch added during the CLI migration in PR #3202. The original System.UnauthorizedAccessException can no longer occur via this path.

Notes

• The current README intentionally favors native binaries (install script / ./build.sh publishbinaries) and no longer documents a container-based local workflow. If a supported docker run path for local authoring is still desired, that's a separate documentation request rather than a bug — suggested follow-up issue: "Document a supported Docker workflow for running docs-builder locally" (a human should decide whether this is wanted).
• Searches for related README / Docker / run-instruction issues surfaced nothing with the same scope; Formal process for creating new automation/helpers #1394 ("Formal process for creating new automation/helpers") is a different topic, so no dedup is suggested.