docs(self-host): document HOPP_ALTERNATE_PORT and non-root containers

[mirarifhasan]

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 is HOPP_ALTERNATE_PORT and 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

• Renamed the variable in the sample .env blocks and the variable lists on both install-and-build pages, and in the self-hosting guide article. The legacy HOPP_AIO_ALTERNATE_PORT still works as an AIO fallback but is no longer advertised.
• New "Running under a non-root user" section on both install-and-build pages: the docker run --user 1000:0 example, the OpenShift Service/Route note, the per-image reserved-port table, and the writable-root-filesystem + GID 0 requirements.
• Subpath warnings now point at HOPP_ALTERNATE_PORT and link to the new section.
• Enterprise only: port 9159 (the local proxy server, started when LOCAL_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

• Reserved ports are documented per image rather than as one flat list, because the images genuinely reserve different sets — the flat list in .env.example tells an admin-image operator to avoid ports it never binds. Values are taken from the RESERVED_PORTS arrays in aio_run.mjs and each package's prod_run.mjs.
• The ClickHouse audit-log export fix from selfhost-enterprise#248 has no configuration surface, so it isn't documented — it just makes exports work under a non-root UID.
• The AIO multiport case (a value set there is ignored with a warning) is deliberately left out: nothing breaks, so it didn't earn space in a deploy guide.

[Copilot]

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_PORT with HOPP_ALTERNATE_PORT and updates subpath warnings accordingly.
• Adds “Container Runtime Config” guidance in .env examples 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.