Skip to content

docs: document container image tags and mount points - #59142

Open
ashrafumair111-lab wants to merge 5 commits into
anomalyco:devfrom
ashrafumair111-lab:container-guidance
Open

ashrafumair111-lab wants to merge 5 commits into
anomalyco:devfrom
ashrafumair111-lab:container-guidance

Conversation

@ashrafumair111-lab

@ashrafumair111-lab ashrafumair111-lab commented Oct 26, 2026 •

Copy link
Copy Markdown

Issue for this PR

Closes #59113

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

The intro page described the container image in a single line with a versioned tag, with no link to where images are published and no guidance on what to mount. This replaces that line with:

  • A direct link to the GitHub Packages page for the container image.
  • A runnable docker run example with standard volume mounts.
  • A table explaining /root (for persistent configuration, agent settings, and credentials) and /workspace (for project mounting), along with guidance to keep them separate.

The heading changes from "Docker" to "Container", as suggested in the issue.

How did you verify your code works?

  • Validated MDX compilation and Markdown syntax with @mdx-js/mdx and remark-gfm.
  • Confirmed table structure (3 columns × 4 rows) and link target.
  • Verified mount recommendations against packages/cli/Dockerfile.
  • Confirmed no other documentation pages link to the old #docker anchor.

Screenshots / recordings

N/A (Documentation change)

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Related: #55558, #57228

ashrafumair111-lab and others added 2 commits October 26, 2026 07:28
The intro page only listed a versioned image tag, so readers could not find
the published package or know which directories to mount. Link the GitHub
Packages page and add a table covering `/root` for configuration persistence
and `/workspace` for the project mount, with a runnable example.

Closes anomalyco#59113

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good. It's a docs-only change, so there was nothing to run. I checked it against packages/cli/Dockerfile: the image runs as root with no WORKDIR, so keeping config under /root and passing -w /workspace for the project is correct. Nothing on the site links to the old #docker anchor. The public API is unchanged.

Two small points, neither blocking:

  • The example tag 2.0.0 was already on the page before this change. The newest v2 release is 2.1.4, so you may want to bump it in both places.
  • #57233 also edits this section of index.mdx, so whichever merges second will need a small conflict fix.

Related: #55558, #57228

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new changes to review. The new commit only merges dev into the branch, and the docs change is the same as before. The public API is unchanged.

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example image tag is now 2.1.4, the current release, which addresses my earlier point. Nothing else in the docs changed, and the public API is unchanged.

@DoctorD90

Copy link
Copy Markdown

Hi! About the changes related to container's docs, may I suggest/ask a couple of stuff?

  1. I have write a suggestion for the run command :) let me know your feedback!
  2. What do you think about creating a minimal compose.yaml file too?
  3. Opencode has many "features" (serve, web, etc); are they available in container too right (I didn't check it out yet); what do you think (for the compose.yaml) to add them if possible? Or even as separated run commands?

@ashrafumair111-lab

ashrafumair111-lab commented Oct 26, 2026 •

Copy link
Copy Markdown
Author

Thanks for the feedback, and no need to apologise — the v2 docs live under services/www/src/docs/content/; there's no top-level docs/ folder, so it's easy to miss.

Your run command suggestion hasn't come through on this PR yet (no review comment so far). Please post it on services/www/src/docs/content/index.mdx and I'll apply it.

serve, pair and acp all work in the container, because the entrypoint is opencode:

docker run --rm -p 4096:4096 \
  -v opencode-config:/root \
  -v "$PWD:/workspace" -w /workspace \
  ghcr.io/anomalyco/opencode:2.1.4 serve --hostname 0.0.0.0 --port 4096

I verified all three on 2.1.4: it runs as root with HOME=/root, and /workspace is created by Docker when you mount it. That's why the table keeps /root for config and credentials, and /workspace for the project.

A minimal compose.yaml is a good idea, but I'd keep it out of this PR:

Better as a follow-up container page once those settle.

The latest tag is a release-pipeline decision rather than a docs one, so best asked to the maintainers on the issue.

Comment thread services/www/src/docs/content/index.mdx Resolved

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new changes to the docs. The new commit only merges dev, and the change itself is the same as in my last review. The public API is unchanged.

@DoctorD90

Copy link
Copy Markdown

serve, pair and acp all work in the container, because the entrypoint is opencode

Hello @ashrafumair111-lab, excuse me, I was trying commands as you mentioned, but I wasn't able to run them or use them properly.

  • If I run pair, I get the link/qrcode but it doesn't work cause the container stops immediately after;
  • If I run serve/service, it doesn't provide me the auth info to get connected;
  • I haven't tried acp cause it was out-of-scope for me in this moment (just using opencode form browser).

May I kindly ask you/suggest, to add a really few lines, on how to run such commands effectively using containers to allow/be able to use the web interface?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Container 'latest' tag and docs references

2 participants