Want to host Kowl under a sub-path (instead of
/)? Then this is the document you're looking for.
There are 3 config entries that should cover most scenarios.
As you can see in docs/config/kowl.yaml the config entries can be found in the
The sub-path under which Kowl will be hosted. If you have a proxy in front of Kowl that sets the
X-Forwarded-Prefixheader and you didn't disable the
setBasePathFromXForwardedPrefixsetting (enabled by default), then you don't need to set this.
Default: not set / empty string
If true, Kowl will check the
X-Forwarded-Prefixheader on incoming requests, and if the header is present its value will be used as the path prefix.
That means if a request has
X-Forwarded-Prefixset, the value set in the
basePathsetting will be ignored.
If you're hosting Kowl on a sub-path and are using a reverse-proxy like Traefik with its "StripPrefix" middleware enabled, disable this setting!
Some proxies (like Traefik with its "StripPrefix" middleware) can remove a prefix from the URL path of an request before forwarding it. This can lead to a situation where both the proxy and Kowl will try to remove a prefix which could lead to issues.
If a prefix is set/used it must be removed at some point before reaching Kowls internal routing. We reccommend that only one part of the stack removes the prefix (even though a scenario where this is a problem is unlikely). So if you're using Traefik (or any other proxy that modifies the request path / URL) you should either set
stripPrefix: falsein Kowl, or configure the proxy so it doesn't modify the path of a request.
See the example below for a setup where the double remocal is a problem.
For the curious, here is an example scenario that, albeit pretty contreived, should illustrate nicely how double removal could be a problem:
- Traefik configured to route
/topicsto Kowl and enabled "StripPrefix" middleware
- Kowl configured with the default settings
- A user types the following address into their browser
- Traefik sees the incoming request path
/topics/topics/example-topic, sees that the prefix matches and removes it so the path becomes
/topics/example-topic, and finally sets
- The request reaches Kowl, which sees that
X-Forwarded-Prefixis set and
setBasePathFromXForwardedPrefixis true. So it tries to remove what it thinks is the prefix with the request path
- Kowl tries to find a handler for the route
/example-topicbut of course it won't find one.