Run CodeGate on remote host

docs/how-to/configure.md

@@ -42,3 +42,56 @@ docker run --name codegate -d -p 8989:8989 -p 9090:9090 \
   --mount type=volume,src=codegate_volume,dst=/app/codegate_volume \
   --restart unless-stopped ghcr.io/stacklok/codegate
 ```
+
+## Run CodeGate on a remote host
+
+:::warning
+
+Keep security aspects in mind and run CodeGate only on a remote host within a
+local or otherwise secured network. CodeGate should not be run on a remote host
+that is directly accessible from the Internet!
+
+:::
+
+The CodeGate web dashboard provided in the Docker container expects the CodeGate
+API to be available on _localhost_ port 8989. Currently this is statically set
+during build time and cannot be changed with a runtime configuration parameter.
+
+Hence to run CodeGate on a remote host you need to build your own appropriately
+customized Docker container image from the CodeGate GitHub repository. Use the
+following steps as a reference and adjust them for your own setup:
+
+1. Clone the CodeGate GitHub repository:
+
+   ```shell
+   git clone https://github.com/stacklok/codegate.git
+   cd codegate
+   ```
+
+2. Edit `./Dockerfile` to add the `VITE_BASE_API_URL` environment variable
+   _before_ the web dashboard build step:
+
+   ```dockerfile {1-3} title="./Dockerfile"
+   # Customize the API base URL
+   ENV VITE_BASE_API_URL=http://<REMOTE_HOST>:8989
+   # End customization
+
+   # Install the webapp dependencies and build it
+   RUN npm install
+   RUN npm run build
+   ```
+
+   Replace `<REMOTE_HOST>` with the IP or DNS name of the remote host where
+   CodeGate will run.
+
+3. Build the customized Docker image on the remote host:
+
+   ```shell
+   make image-build
+   ```
+
+4. Run the customized Docker image (built locally as `codegate:latest`):
+
+   ```shell
+   docker run --name codegate -d -p 8989:8989 -p 9090:9090 -p 8990:8990 --mount type=volume,src=codegate_volume,dst=/app/codegate_volume --restart unless-stopped codegate:latest
+   ```

docs/how-to/install.md

@@ -16,6 +16,16 @@ replace `docker` with `podman` in all commands.
 
 ## Run CodeGate
 
+CodeGate is primarily intended as a single-user system. There is no
+authentication when using the CodeGate API or the CodeGate web dashboard which
+are both operating over unencrypted HTTP. Hence all CodeGate components are
+supposed to bind to _localhost_ (`127.0.0.1`) and remain inaccessible from
+remote hosts.
+
+If you are an advanced user who wants to run CodeGate on a remote host in a
+secured/local network, see
+[Run CodeGate on a remote host](./configure.md#run-codegate-on-a-remote-host).
+
 ### Recommended settings
 
 To download and run CodeGate with the recommended configuration for full

docusaurus.config.ts

@@ -182,7 +182,7 @@ const config: Config = {
     prism: {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
-      additionalLanguages: ['bash', 'json', 'powershell'],
+      additionalLanguages: ['bash', 'json', 'powershell', 'docker'],
     },
     mermaid: {
       theme: { light: 'neutral', dark: 'dark' },