docs: add Docker install instructions - #163
Draft
sanity wants to merge 1 commit into
Draft
Conversation
freenet-core#5516 publishes an official container image to ghcr.io/freenet/freenet-core for every release, built for linux/amd64 and linux/arm64. Nothing on the site mentioned it. Adds /quickstart/docker/ covering the one-liner, compose, ports, checking on a running node, and the two things that are easy to get wrong: - The image keeps itself updated. That is worth stating plainly, because the usual container habit is to pull a new image, and a Freenet peer that falls far enough behind is refused by the network rather than merely missing features. No Watchtower, no cron, no remembering to pull. - It wants `--network host`. Under Docker's default bridge network the dashboard is unreachable (the API binds loopback, which is the container's loopback, and publishing the port does not help because nothing is listening on an address it forwards to) and UDP hole punching degrades. The bridge fallback is documented along with what it costs. Placement: Docker is offered inside the Linux tab of the install picker rather than as a fourth tab. The tabs select an operating system and Docker is not one, and host networking, which is the mode where the dashboard works, is Linux in practice anyway. Someone who wants the app on their own machine still sees one instruction. Also rewrites the "Containers & headless servers" troubleshooting note. It described the installer failing inside an existing container, which reads as discouraging now that there is an image; it now points at the image first and keeps the `--system` advice for people running the installer in a container themselves. Claude-Session: https://claude.ai/code/session_01W2mLM7JF3KC6UfTB4Zqwf6
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
1 participant
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.
Problem
freenet-core#5516 is merged and publishes an official container image to
ghcr.io/freenet/freenet-corefor every release, forlinux/amd64andlinux/arm64. Nothing on the site mentions it.What this adds
A new page at
/quickstart/docker/covering thedocker runone-liner, a compose file, ports, how to check on a running node, and the two things that are easy to get wrong.It keeps itself updated. Worth stating plainly, because the usual container habit is to pull a new image when you remember. A Freenet peer that falls far enough behind is refused by the network rather than merely missing features, so the image applies updates itself the way the desktop install does. No Watchtower, no cron job.
It wants
--network host. Under Docker's default bridge network the dashboard is unreachable: the local API binds loopback, which under bridge is the container's loopback, and publishing the port does not help because nothing is listening on an address it forwards to. UDP hole punching also degrades, because bridge networking rewrites the source port. The bridge fallback is documented along with what it costs, for people on Docker Desktop who have no choice.Placement
Docker is offered inside the Linux tab of the install picker rather than as a fourth tab.
The tabs select an operating system and Docker is not one. Host networking, which is the mode where the dashboard actually works, is Linux in practice anyway. And someone who just wants Freenet on their own laptop should still see exactly one instruction, not a fork in the road.
It renders as a quiet footnote under the install command, not a competing option:
Happy to move it if you'd rather it were more prominent, or add it to the nav.
Also
Rewrote the "Containers & headless servers" troubleshooting note. It described the installer failing inside an existing container, which now reads as discouraging when there is a supported image. It points at the image first and keeps the
--systemadvice for people running the installer in a container themselves.Testing
hugobuilds clean,/quickstart/docker/renders, and the links resolve from both the Linux tab and the troubleshooting note.Do not merge yet
The image does not exist until a release publishes it. freenet-core#5516 only just merged, and
docker-publish.ymlfires onrelease: published, soghcr.io/freenet/freenet-corehas no tags right now. Merging this before then would ship instructions that fail with what looks like a missing image.There is also a one-time step after that first publish: GitHub creates the package private by default, so its visibility has to be set to public once before anyone outside the org can pull it.
So the order is: release goes out, image publishes, package set public, then this merges. I am tracking the first three and will comment here when they are done.
[AI-assisted - Claude]
https://claude.ai/code/session_01W2mLM7JF3KC6UfTB4Zqwf6