Base context path can be changed (#88) #1424

s4s0l · 2025-12-08T12:45:29Z

Summary

Issue: #88 (changing base context root for hosting behind url rewriting reverse proxy)

based on work done here: https://github.com/simonhammes/gatus/tree/88-dynamic-base, that exists as a draft PR (Add subpath support #908)
Additions:
- docker compose for testing reverse proxy scenario
- rolled back 'SERVER_URL' in order to allow hosting ui via node during development
- updated manifest.json so it will honour relative paths

Checklist

Tested and/or added tests to validate that the changes work as intended, if applicable.
- make run && make frontend-run, seems to work
- make docker-build-and-run works also
- I've allowed myself to add compose file that runs gatus behind caddy, to proove it actually works.
  - While behind proxy installed an 'app' from edge - icons and stuff were present in my 'start' menu
Updated documentation in README.md.

Notes:

I didn't try to make 'make test' not - fail on my PC. Before and after my changes same 2 tests fail - i assume they have nothing to do with UI anyway (DNS and ICMP tests).
For anyone wanting to test it or use my version there is 'ghcr.io/s4s0l/gatus:v0.0.0.0.4' image that contains this PR.

- based on work done here: https://github.com/simonhammes/gatus/tree/88-dynamic-base - Additions: - docker compose for testing reverse proxy scenario - rolled back 'SERVER_URL' in order to allow hosting ui via node during development - updated manifest.json so it will honour relative paths

.examples/docker-compose-reverse-proxy/compose.yml

Makefile

.examples/docker-compose-reverse-proxy/compose.yml

PythonGermany · 2025-12-09T00:30:50Z

README.md

 | `ui.dashboard-subheading`    | Dashboard description between header and endpoints                                                                                       | `Monitor the health of your endpoints in real-time` |
 | `ui.header`                  | Header at the top of the dashboard.                                                                                                      | `Gatus`                    |
 | `ui.logo`                    | URL to the logo to display.                                                                                                              | `""`                       |
+| `ui.base`                    | `href` attribute of the HTML `<base>` tag. Use this if you want to host Gatus on a subpath (e.g. `/status/`). Has to end with '/'.       | `/`                        |


I think this option might actually be better fit in the web config section and maybe also renaming it to make it easier to read without the actually reading the docs: web.base-path

This time I'll ask before doing anything. The value of the 'base path' is needed by the 'UI config' (to render index.html) and by the 'security config' (for proper redirects and cookie paths). Currently, these parts are quite isolated, and I'm about to introduce a dependency from UI & security to web config. I can think of a plethora of ways of doing it, but I get a feeling there will be a few back-and-forth discussions over it 😉. What do you think about passing 'basePath' as an argument to 'ValidateAndSetDefaults' in these different configuration objects that need it? This way it won't introduce dependencies to 'web' config everywhere, will be easily mocked in tests, and this method is mutating everything anyway...or is somewhere else a pattern I can use?

Currently commited version does that. It is by no means final; still missing some validation and tests, but it works.

What do you think about passing 'basePath' as an argument to 'ValidateAndSetDefaults' in these different configuration objects that need it?

I think your suggested solution passing it as argument might not scale very well in case there are more options that have the same problem are added in the future.

I opened a PR on your fork with another solution that so far looks like it is consistent with the MaximumNumberOfResults storage option where we would not need to add any additional arguments or package dependencies.

Doing this 'your' way has a drawback, that it makes it difficult to validate the RedirectURL in oidc configuration, as validation occurs before settings are distributed. But I'm not entirely sure there is a universe where not including a base-path in redirect url is a desired thing.

Anyway I think I've finished.

README.md

Makefile

Co-authored-by: PythonGermany <[email protected]>

…ange.

PythonGermany · 2025-12-09T22:53:01Z

README.md

 Currently, you can expose the Gatus UI using a fully qualified domain name (FQDN) such as `status.example.org`. However, it does not support path-based routing, which means you cannot expose it through a URL like `example.org/status/`.

 For more information, see https://github.com/TwiN/gatus/issues/88.


Needs to be updated

refactor: Update how base-path cross config is handled

PythonGermany · 2025-12-10T20:36:54Z

security/oidc.go

 }

 func (c *OIDCConfig) loginHandler(ctx *fiber.Ctx) error {
+	// ??? state and nonce are not 'secure random'


I do not quite understand what you mean. Can you elaborate on it?

Note to myself to think about it and open separate issue. Didn't intend to push it. Not related to this PR.

What I was wondering was that 'state' in oauth flow is kinda important. This value should not be easily guessable. I don't know how UUID is implemented here but UUIDs are usually quite 'guessable'. By 'secure random' i meant something like https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html. crypto in go probably has something like this.

PythonGermany · 2025-12-11T14:12:47Z

We missed a location where we need to update the base path:

gatus/web/app/src/components/Settings.vue

Lines 133 to 135 in 862613e

    
           const setThemeCookie = (theme) => { 
        
             document.cookie = `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; samesite=strict` 
        
           }

s4s0l · 2025-12-11T19:09:31Z

There is #1430, I think i'll wait with rebase until it gets merged.

PythonGermany · 2025-12-16T23:18:56Z

web/app/src/components/ResponseTimeChart.vue

  },
  serverUrl: {
    type: String,
    default: '..'


Should the default also be changed?

Probably. In my opinion default should be removed. It is used only once, and where it is used it is set explicitly. Default for this kind of stuff does not make much sense to me. If it is not set consequently throughout the application it will not work, but will not fail during type checking / linting.

PythonGermany reviewed Dec 8, 2025

View reviewed changes

.examples/docker-compose-reverse-proxy/compose.yml Show resolved Hide resolved

PythonGermany reviewed Dec 8, 2025

View reviewed changes

Makefile Outdated Show resolved Hide resolved

chore: review fixes - reverse proxy example moved to examples.

10d5114

s4s0l force-pushed the 88-dynamic-base-followup branch from 7c42ced to 10d5114 Compare December 8, 2025 21:55

PythonGermany reviewed Dec 8, 2025

View reviewed changes

.examples/docker-compose-reverse-proxy/compose.yml Outdated Show resolved Hide resolved

PythonGermany reviewed Dec 9, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

PythonGermany reviewed Dec 9, 2025

View reviewed changes

Makefile Show resolved Hide resolved

s4s0l and others added 3 commits December 9, 2025 08:45

chore: revert empty lines

ab21f58

Co-authored-by: PythonGermany <[email protected]>

fix: web.base-path instead of ui.base, oidc aware of context patch ch…

df91cb2

…ange.

refactor: Update how base-path cross config is handled

fc76566

PythonGermany mentioned this pull request Dec 9, 2025

refactor: Update how base-path cross config is handled s4s0l/gatus#1

Merged

PythonGermany reviewed Dec 9, 2025

View reviewed changes

s4s0l and others added 4 commits December 10, 2025 10:49

Merge pull request #1 from PythonGermany/add-base-path-support

4869fea

refactor: Update how base-path cross config is handled

test: Tests for custom base-path

0572514

docs: base path documentation update, oicd example mentioned

6345796

docs: bad dir name in example

862613e

PythonGermany reviewed Dec 10, 2025

View reviewed changes

PythonGermany reviewed Dec 16, 2025

View reviewed changes

		Currently, you can expose the Gatus UI using a fully qualified domain name (FQDN) such as `status.example.org`. However, it does not support path-based routing, which means you cannot expose it through a URL like `example.org/status/`.

		For more information, see https://github.com/TwiN/gatus/issues/88.

Uh oh!

Base context path can be changed (#88) #1424

Are you sure you want to change the base?

Base context path can be changed (#88) #1424

Uh oh!

Conversation

s4s0l commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

Notes:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PythonGermany commented Dec 11, 2025

Uh oh!

s4s0l commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

s4s0l commented Dec 8, 2025 •

edited

Loading