docs(self-host): document HOPP_ALTERNATE_PORT and non-root containers#361
Open
mirarifhasan wants to merge 2 commits into
Open
docs(self-host): document HOPP_ALTERNATE_PORT and non-root containers#361mirarifhasan wants to merge 2 commits into
mirarifhasan wants to merge 2 commits into
Conversation
The self-host images can now run under a non-root / arbitrary UID (hoppscotch#6481, selfhost-enterprise#248). Caddy's in-container HTTP port is configurable via HOPP_ALTERNATE_PORT, which replaces the AIO-only HOPP_AIO_ALTERNATE_PORT and is honoured by the frontend, backend and admin images too. - Rename the variable in the sample .env blocks and variable lists - Add a "Running under a non-root user" section covering the OpenShift / rootless Docker / Podman setup, the per-image reserved ports, the port mapping update, and the writable-rootfs + GID 0 requirements - Enterprise: reserve 9159 (local proxy server) and note that the ClickHouse image is not arbitrary-UID safe
There was a problem hiding this comment.
Pull request overview
Updates self-hosting documentation to reflect the newer HOPP_ALTERNATE_PORT variable and to document how to run Hoppscotch self-host images under non-root / arbitrary-UID container constraints (rootless Docker/Podman, OpenShift, etc.).
Changes:
- Replaces references to
HOPP_AIO_ALTERNATE_PORTwithHOPP_ALTERNATE_PORTand updates subpath warnings accordingly. - Adds “Container Runtime Config” guidance in
.envexamples and introduces “Running under a non-root user” sections (incl. reserved-port tables) on install-and-build pages. - Adds an enterprise-only reserved-port note for the local proxy server (
9159) and a ClickHouse/OpenShift caution for audit logs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| guides/articles/self-host-hoppscotch-on-your-own-servers.mdx | Updates the self-hosting guide’s .env example and subpath warning to reference HOPP_ALTERNATE_PORT and link to the new non-root guidance. |
| documentation/self-host/enterprise-edition/install-and-build.mdx | Renames the variable, adds non-root runtime guidance (incl. reserved ports + enterprise-specific notes), and updates subpath warnings. |
| documentation/self-host/community-edition/install-and-build.mdx | Renames the variable, adds non-root runtime guidance (incl. reserved ports), and updates subpath warnings. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address AI review feedback: reword the subpath warnings so they explain that ports below 1024 are privileged and non-root users can't bind them (a rootless/OpenShift restriction), rather than implying it's host-specific. Also clarify that images serve on port 80 inside the container to avoid ambiguity with the host-published port mappings.
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.
Closes BE-786
Documents the non-root / arbitrary-UID container support landed in hoppscotch/hoppscotch#6481 and hoppscotch/selfhost-enterprise#248.
The docs only knew
HOPP_AIO_ALTERNATE_PORT, described as an AIO-only way to move the subpath endpoint off port 80. That's now stale twice over: the variable isHOPP_ALTERNATE_PORTand applies to the frontend, backend and admin images as well, and its real purpose is making the images runnable under a non-root UID rather than just dodging a port clash.What's changed
.envblocks and the variable lists on both install-and-build pages, and in the self-hosting guide article. The legacyHOPP_AIO_ALTERNATE_PORTstill works as an AIO fallback but is no longer advertised.docker run --user 1000:0example, the OpenShift Service/Route note, the per-image reserved-port table, and the writable-root-filesystem + GID0requirements.HOPP_ALTERNATE_PORTand link to the new section.9159(the local proxy server, started whenLOCAL_PROXY_SERVER_ENABLE=true) appears in the reserved-port table for the AIO and backend images, and a warning notes that the official ClickHouse image is not arbitrary-UID safe — an OpenShift deployment needs a managed or external ClickHouse.Notes to reviewers
.env.exampletells an admin-image operator to avoid ports it never binds. Values are taken from theRESERVED_PORTSarrays inaio_run.mjsand each package'sprod_run.mjs.