Add configurable base path

[pascal-cm]

• I have read and understand the pull request rules.

Description

Synopsis

Adds capabilities to Dockge for deployments under a custom base path (e.g. http://localhost:5001/dockge/).

Rationale

Currently Dockge lacks the ability to be deployed under a base path other than the default /, which is a common requirement for services running behind a reverse proxy. This PR modifies the frontend, backend and the Docker Compose manifest to allow for Dockge to run under any path.

The base path may be set during deployment – no frontend or image re-building required.

Works in local development via npm run dev, too.

Changed files

Most of the magic happens by setting Vite's base option and exposing it as <base href="%BASE_URL%">. While the build time value of ./ solves some of the requirements, the remaining code is to change the relative path to the value of DOCKGE_BASE_PATH at runtime.

The code around it for the server part is about mutating index.hmtl (in mutateIndexHTML()) to include a dynamic <base href="..." /> , while on client side, the base tag's href value is used for URL construction (socket = io(url, { path: new URL("socket.io", document.baseURI).pathname });).

Project

• package.json
  • add node-html-parser (MIT licensed, dependencies MIT and BSD-2-Clause licensed)
• package-lock.json
  • as above

Frontend

• index.html
  • Add base tag
• vite.config.ts
  • Read .env (to use the same values as the server from .env)
  • Add base option
  • Configure Vue plugin to modify object assets
• socket.ts
  • Use path from base tag

Backend

• dockge-server.ts
  • add basePath option
  • mutate index.html with basePath
• util-server.ts
  • add helper function

Docker

• compose.yaml
  • add DOCKGE_BASE_PATH env var
• healthcheck.go
  • modify URL to include base path

Testing

As Dockge seemingly does not have any automated tests suites, all tests were conducted manually.

This script may be used as a quick way for assessment:

#!/usr/bin/env bash

set -e
set -x

npm install
npm run build:frontend
docker buildx build --tag louislam/dockge:build-healthcheck --file docker/BuildHealthCheck.Dockerfile .
docker buildx build --tag louislam/dockge:base --file docker/Base.Dockerfile .
node ./extra/env2arg.js docker buildx build --tag louislam/dockge:latest --tag louislam/dockge:1 --target release --file docker/Dockerfile .

Run the script without configuring DOCKGE_BASE_PATH:

docker compose up --force-recreate

Dockge should be running under http://localhost:5001/.

Now configure a base path by setting DOCKGE_BASE_PATH per CLI :

DOCKGE_BASE_PATH=/dockge docker compose up --force-recreate

Dockge should be now be running under http://localhost:5001/dockge/.

If you prefer to keep settings in a .env file, be aware these are also picked up by npm run dev:frontend and npm run dev:backend.

Reverse Proxy Example

When running behind a reverse proxy, both the base path with and without a trailing slash should be proxied. E.g, this snippet configures Caddy to act as a reverse proxy when running Dockge with DOCKGE_BASE_PATH=/dockge.

handle /dockge {
    reverse_proxy dockge:5001
}

handle /dockge/* {
    reverse_proxy dockge:5001
}

Note that the above example is just for illustration and may require addition configuration, such as disabling buffers, etc.

Notes

• Aims to resolve discussion add BASE_PATH variable #874
• Aims to resolve issue [SUGGESTION] Make dockge work with reverse proxy NOT ONLY under /* (for example /admin/dockge/* to dockge:5001) #903

Type of change

Please delete any options that are not relevant.

• New feature (non-breaking change which adds functionality)

Checklist

• My code follows the style guidelines of this project
• I ran ESLint and other linters for modified files
• I have performed a self-review of my own code and tested it
• I have commented my code, particularly in hard-to-understand areas
  (including JSDoc for methods)
• My changes generate no new warnings
• My code needed automated testing. I have added them (this is optional task)