diff --git a/documentation/self-host/community-edition/install-and-build.mdx b/documentation/self-host/community-edition/install-and-build.mdx index aeef17ff..eb791849 100644 --- a/documentation/self-host/community-edition/install-and-build.mdx +++ b/documentation/self-host/community-edition/install-and-build.mdx @@ -19,9 +19,6 @@ Before you get started with the installation, you need to configure the environm # Prisma Config DATABASE_URL=postgresql://username:password@url:5432/dbname # or replace with your database URL -# (Optional) By default, the AIO container (when in subpath access mode) exposes the endpoint on port 80. Use this setting to specify a different port if needed. -HOPP_AIO_ALTERNATE_PORT=80 - # Sensitive Data Encryption Key while storing in Database (32 character) DATA_ENCRYPTION_KEY=******************************** @@ -52,20 +49,26 @@ VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy # Set to `true` for subpath based access ENABLE_SUBPATH_BASED_ACCESS=false + +#-----------------------Container Runtime Config---------------------# + +# (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset. +# Set a free port (for example 8000) to run the container under a non-root UID. +# HOPP_ALTERNATE_PORT=8000 ``` Let's understand the major environment variables: 1. `DATABASE_URL`: This is where you add your Postgres database URL. -2. `HOPP_AIO_ALTERNATE_PORT`: This is an optional variable that lets you specify an alternate port for the AIO container's endpoint when operating in subpath access mode. By default, this endpoint is exposed on port 80. -3. `DATA_ENCRYPTION_KEY`: A 32-character key used for encrypting sensitive data stored in the database. -4. `WHITELISTED_ORIGINS`: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app. -5. `VITE_BASE_URL`: This is the URL where your deployment will be accessible from. -6. `VITE_SHORTCODE_BASE_URL`: A URL to generate shortcodes for sharing, can be the same as `VITE_BASE_URL`. -7. `VITE_BACKEND_GQL_URL`: The URL for GraphQL within the instance. -8. `VITE_BACKEND_WS_URL`: The URL for WebSockets within the instance. -9. `VITE_BACKEND_API_URL`: The URL for REST APIs within the instance. -10. `VITE_APP_TOS_LINK` and `VITE_APP_PRIVACY_POLICY_LINK` are optional and are used to configure the links to the Terms & Conditions and Privacy Policy. +2. `DATA_ENCRYPTION_KEY`: A 32-character key used for encrypting sensitive data stored in the database. +3. `WHITELISTED_ORIGINS`: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app. +4. `VITE_BASE_URL`: This is the URL where your deployment will be accessible from. +5. `VITE_SHORTCODE_BASE_URL`: A URL to generate shortcodes for sharing, can be the same as `VITE_BASE_URL`. +6. `VITE_BACKEND_GQL_URL`: The URL for GraphQL within the instance. +7. `VITE_BACKEND_WS_URL`: The URL for WebSockets within the instance. +8. `VITE_BACKEND_API_URL`: The URL for REST APIs within the instance. +9. `VITE_APP_TOS_LINK` and `VITE_APP_PRIVACY_POLICY_LINK` are optional and are used to configure the links to the Terms & Conditions and Privacy Policy. +10. `HOPP_ALTERNATE_PORT`: An optional variable that changes the HTTP port Caddy listens on inside the container, which is `80` by default. Set it to run under a non-root user, or when port `80` is already taken. See [running under a non-root user](#running-under-a-non-root-user). Third-party auth configs have to be obtained from the respective providers. You can choose and configure the auth providers by following the [configuring OAuth guide](/documentation/self-host/community-edition/prerequisites#oauth). @@ -160,10 +163,30 @@ When using AIO, when subpath access is set to true the services can be accessed | Hoppscotch Backend | `/backend` | -By default, the AIO container exposes the app on port 80. This can cause conflicts if you're running on a host system where -port 80 is privileged, such as with Rootless Docker, Podman, or hardened environments like OpenShift. If you experience issues on these setups, try setting `HOPP_AIO_ALTERNATE_PORT` to bind the app to a non-privileged port. +By default, the AIO container serves the app on port `80`. Ports below `1024` are privileged, so a non-root user can't bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set `HOPP_ALTERNATE_PORT` to bind the app to a port at or above `1024`. See [running under a non-root user](#running-under-a-non-root-user). +## Running under a non-root user + +By default the images serve on port `80` inside the container (the HTTP port Caddy binds), which a non-root user can't bind since ports below `1024` are privileged. To run under a non-root UID — OpenShift's restricted SCC, rootless Docker, Podman — set `HOPP_ALTERNATE_PORT` to a free port at or above `1024`, run the container with GID `0`, and update your published port mapping to match: + +```bash +docker run --user 1000:0 -p 3000:8000 -e HOPP_ALTERNATE_PORT=8000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch +``` + +On OpenShift the restricted SCC assigns the UID and GID `0` for you; just set the variable and point your Service and Route at the port you chose. If you deploy with the provided `docker-compose.yml`, the container side of the port mapping already follows `HOPP_ALTERNATE_PORT`. + +The port must not collide with one the image already uses, or the container exits at startup naming the conflict: + +| Image | Reserved ports | +| ------------------------- | -------------- | +| AIO (subpath access mode) | `8080`, `3200` | +| Frontend | `3000`, `3200` | +| Backend | `3170`, `8080` | +| Admin | `3100` | + +The container needs a writable root filesystem, and the non-root UID must belong to GID `0`. + ## Migrations Once the instance of Hoppscotch is up, you need to run migrations on the database to ensure that it has the relevant tables. Depending on how Hoppscotch was set up, the method to run the migrations changes. diff --git a/documentation/self-host/enterprise-edition/install-and-build.mdx b/documentation/self-host/enterprise-edition/install-and-build.mdx index 33f1296f..b392fa25 100644 --- a/documentation/self-host/enterprise-edition/install-and-build.mdx +++ b/documentation/self-host/enterprise-edition/install-and-build.mdx @@ -20,9 +20,6 @@ Before you get started with the installation, you need to configure the environm # Get your license key from https://enterprise.hoppscotch.com ENTERPRISE_LICENSE_KEY=*************************************** -# (Optional) By default, the AIO container (when in subpath access mode) exposes the endpoint on port 80. Use this setting to specify a different port if needed. -HOPP_AIO_ALTERNATE_PORT=80 - # Prisma Config DATABASE_URL=postgresql://username:password@url:5432/dbname # or replace with your database URL @@ -74,22 +71,28 @@ LOCAL_PROXY_SERVER_ENABLE=false # Optional: Route all API requests via a proxy server for added security. # Set your proxy server URL here, or remove this variable to send requests directly. PROXY_APP_URL=https://proxy.hoppscotch.io + +#-----------------------Container Runtime Config---------------------# + +# (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset. +# Set a free port (for example 8000) to run the container under a non-root UID. +# HOPP_ALTERNATE_PORT=8000 ``` Let's understand the major environment variables: 1. `ENTERPRISE_LICENSE_KEY`: The license key required to use Hoppscotch Enterprise. 2. `DATABASE_URL`: This is where you add your Postgres database URL. -3. `HOPP_AIO_ALTERNATE_PORT`: This is an optional variable that lets you specify an alternate port for the AIO container's endpoint when operating in subpath access mode. By default, this endpoint is exposed on port 80. -4. `HORIZONTAL_SCALING`: Set to true to enable horizontal scaling, which uses Redis for managing pub-sub and state across instances. -5. `DATA_ENCRYPTION_KEY`: A 32-character key used for encrypting sensitive data stored in the database. -6. `WHITELISTED_ORIGINS`: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app. -7. `VITE_BASE_URL`: This is the URL where your deployment will be accessible from. -8. `VITE_SHORTCODE_BASE_URL`: A URL to generate shortcodes for sharing, can be the same as `VITE_BASE_URL`. -9. `VITE_BACKEND_GQL_URL`: The URL for GraphQL within the instance. -10. `VITE_BACKEND_WS_URL`: The URL for WebSockets within the instance. -11. `VITE_BACKEND_API_URL`: The URL for REST APIs within the instance. -12. `VITE_APP_TOS_LINK` and `VITE_APP_PRIVACY_POLICY_LINK` are optional and are used to configure the links to the Terms & Conditions and Privacy Policy. +3. `HORIZONTAL_SCALING`: Set to true to enable horizontal scaling, which uses Redis for managing pub-sub and state across instances. +4. `DATA_ENCRYPTION_KEY`: A 32-character key used for encrypting sensitive data stored in the database. +5. `WHITELISTED_ORIGINS`: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app. +6. `VITE_BASE_URL`: This is the URL where your deployment will be accessible from. +7. `VITE_SHORTCODE_BASE_URL`: A URL to generate shortcodes for sharing, can be the same as `VITE_BASE_URL`. +8. `VITE_BACKEND_GQL_URL`: The URL for GraphQL within the instance. +9. `VITE_BACKEND_WS_URL`: The URL for WebSockets within the instance. +10. `VITE_BACKEND_API_URL`: The URL for REST APIs within the instance. +11. `VITE_APP_TOS_LINK` and `VITE_APP_PRIVACY_POLICY_LINK` are optional and are used to configure the links to the Terms & Conditions and Privacy Policy. +12. `HOPP_ALTERNATE_PORT`: An optional variable that changes the HTTP port Caddy listens on inside the container, which is `80` by default. Set it to run under a non-root user, or when port `80` is already taken. See [running under a non-root user](#running-under-a-non-root-user). Third-party auth configs have to be obtained from the respective providers. You can choose and configure the auth providers by following the [configuring OAuth guide](/documentation/self-host/enterprise-edition/prerequisites#oauth). @@ -184,10 +187,32 @@ When using AIO, when subpath access is set to true the services can be accessed | Hoppscotch Backend | `/backend` | -By default, the AIO container exposes the app on port 80. This can cause conflicts if you're running on a host system where -port 80 is privileged, such as with Rootless Docker, Podman, or hardened environments like OpenShift. If you experience issues on these setups, try setting `HOPP_AIO_ALTERNATE_PORT` to bind the app to a non-privileged port. +By default, the AIO container serves the app on port `80`. Ports below `1024` are privileged, so a non-root user can't bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set `HOPP_ALTERNATE_PORT` to bind the app to a port at or above `1024`. See [running under a non-root user](#running-under-a-non-root-user). +## Running under a non-root user + +By default the images serve on port `80` inside the container (the HTTP port Caddy binds), which a non-root user can't bind since ports below `1024` are privileged. To run under a non-root UID — OpenShift's restricted SCC, rootless Docker, Podman — set `HOPP_ALTERNATE_PORT` to a free port at or above `1024`, run the container with GID `0`, and update your published port mapping to match: + +```bash +docker run --user 1000:0 -p 3000:8000 -e HOPP_ALTERNATE_PORT=8000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise +``` + +On OpenShift the restricted SCC assigns the UID and GID `0` for you; just set the variable and point your Service and Route at the port you chose. If you deploy with the provided `docker-compose.yml`, the container side of the port mapping already follows `HOPP_ALTERNATE_PORT`. + +The port must not collide with one the image already uses, or the container exits at startup naming the conflict. Port `9159` is the local proxy server, which the backend starts when `LOCAL_PROXY_SERVER_ENABLE` is `true`: + +| Image | Reserved ports | +| ------------------------- | ---------------------- | +| AIO (subpath access mode) | `8080`, `3200`, `9159` | +| Frontend | `3000`, `3200` | +| Backend | `3170`, `8080`, `9159` | +| Admin | `3100` | + +The container needs a writable root filesystem, and the non-root UID must belong to GID `0`. + +The ClickHouse container used for [audit logs](/guides/articles/audit-logs) is the official `clickhouse/clickhouse-server` image, which expects to run as its own UID and is not arbitrary-UID safe. On OpenShift, use a managed or externally hosted ClickHouse instead of running it alongside Hoppscotch under the restricted SCC. + ## Migrations Once the instance of Hoppscotch is up, you need to run migrations on the database to ensure that it has the relevant tables. Depending on how Hoppscotch was set up, the method to run the migrations changes. diff --git a/guides/articles/self-host-hoppscotch-on-your-own-servers.mdx b/guides/articles/self-host-hoppscotch-on-your-own-servers.mdx index 5a4c2ffb..762b4a18 100644 --- a/guides/articles/self-host-hoppscotch-on-your-own-servers.mdx +++ b/guides/articles/self-host-hoppscotch-on-your-own-servers.mdx @@ -33,9 +33,6 @@ Create a `.env` file in your working directory, copy the example environment var # Prisma Config DATABASE_URL=postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch -# (Optional) By default, the AIO container (when in subpath access mode) exposes the endpoint on port 80. Use this setting to specify a different port if needed. -HOPP_AIO_ALTERNATE_PORT=80 - # Sensitive Data Encryption Key while storing in Database (32 character) DATA_ENCRYPTION_KEY=******************************** @@ -66,6 +63,12 @@ VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy # Set to `true` for subpath based access ENABLE_SUBPATH_BASED_ACCESS=false + +#-----------------------Container Runtime Config---------------------# + +# (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset. +# Set a free port (for example 8000) to run the container under a non-root UID. +# HOPP_ALTERNATE_PORT=8000 ``` ### 1. Database Configuration @@ -166,7 +169,7 @@ Subpath access allows you to host multiple services under a single domain by ass When `ENABLE_SUBPATH_BASED_ACCESS=true`, you can access all three services (Hoppscotch App, Admin Dashboard, Hoppscotch Backend) on the same domain using different routes. If subpath access is disabled **(`ENABLE_SUBPATH_BASED_ACCESS=false`)**, you will need to access the services on different ports. -By default, the AIO container exposes the app on port 80. This can cause conflicts if you're running on a host system where port 80 is privileged, such as with Rootless Docker, Podman, or hardened environments like OpenShift. If you experience issues on these setups, try setting `HOPP_AIO_ALTERNATE_PORT` to bind the app to a non-privileged port. +By default, the AIO container serves the app on port `80`. Ports below `1024` are privileged, so a non-root user can't bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set `HOPP_ALTERNATE_PORT` to bind the app to a port at or above `1024` — see [running under a non-root user](/documentation/self-host/community-edition/install-and-build#running-under-a-non-root-user) for the full details. ## Installing dependencies, running migrations & building the image