docs(readme): lead the Docker section with the published image - #2196
Merged
Conversation
The section only ever documented `docker build`, so every reader compiled the image locally even though `ghcr.io/mempalace/mempalace` is published multi-arch. Worse, a clone builds `develop` (the default branch), not the release — a build and a pull could hand you different versions with no hint that they differ. Lead with `docker pull`, and cover the things that actually cost people an evening: - the container only sees what you mount, so the MCP client config now mounts a transcripts directory; without it the server starts fine and every mine finds nothing - paths become container paths after that, and `~` / `$HOME` are not expanded by every MCP client - the first embedding call downloads ~80 MB (minilm) or ~300 MB (embeddinggemma) into /data, which reads as a hung container - bind mounts keep host ownership and the image runs as uid 1000, so a 0700 directory fails with a bare PermissionError on Linux; Docker Desktop's uid mapping hides this on macOS and Windows. `--user` is called out as the wrong fix — /data is mode 700 owned by uid 1000, so another uid cannot write the palace at all - mining never writes to its source, so the examples mount it read-only - the GPU image is x86_64-only; onnxruntime-gpu has no aarch64 Linux wheels, so that build fails on Apple Silicon Every command in the section was run as written against the published image, and each claim checked rather than assumed: the uid and mode of /data read out of the image, `--user` confirmed to break a *fresh* volume, the read-only mount confirmed to still mine, and the aarch64 GPU failure reproduced.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Last piece of the #2177 follow-up, after #2187, #2188, #2189 and making the GHCR package public.
Why
The section only documented
docker build, so every reader compiled locally even though the image is published multi-arch. And a clone buildsdevelop— the default branch — not the release, so a build and a pull can hand you different versions with nothing saying so.Beyond that it omitted the things that actually cost people time. All of these are verified below, not guessed.
What changed
docker pull ghcr.io/mempalace/mempalace:latest; building moved to the end, where it belongs (still required for the GPU variant, which is not published).mempalace_mine, and there was nothing there. Notes that paths are container paths from then on, and that~/$HOMEare not expanded by every MCP client./data— it reads as a hung container otherwise.0700directory fails with a barePermissionError: [Errno 13]. Docker Desktop maps uids on macOS/Windows, which is why this is invisible to most of us — our own CI hit it in ci(docker): run the image before publishing it #2189.--useris explicitly called out as the wrong fix.:ro, since mining never writes to it.Verification
Every command in the new section was run as written, against the published image on a fresh volume:
pull→mine /work:rofiles a drawer →searchreturns it verbatim from a separate container → the MCPargsarray, verbatim, completes aninitializehandshake. The untaggedghcr.io/mempalace/mempalaceform used in the examples resolves correctly.Claims checked rather than assumed:
/datais uid 1000, mode 700statinside the image--useris the wrong fix--user 1234:1234fails on a fresh volume, not just an existing one:ro:ro,mine --mode convosfiled and returned itdevelop, not the releaseDockerfile.gpubuild reproduced failing on aarch64:onnxruntime-gpu (v1.25.0) only has wheels for manylinux_2_27_x86_64, manylinux_2_28_x86_64, win_amd64tests/test_readme_claims.py: 42 passed.Not included
website/guide/still has nodocker.md— the docs site covers Antigravity, Cursor, OpenClaw and others, but not Docker, so this README section remains the only Docker documentation. Separate PR if you want it.