Hosting

Want to host Kowl under a sub-path (instead of /)? Then this is the document you're looking for.

Config Entries

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 server: group.

  • basePath

    The sub-path under which Kowl will be hosted. If you have a proxy in front of Kowl that sets the X-Forwarded-Prefix header and you didn't disable the setBasePathFromXForwardedPrefix setting (enabled by default), then you don't need to set this.

    Default: not set / empty string

  • setBasePathFromXForwardedPrefix

    If true, Kowl will check the X-Forwarded-Prefix header 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-Prefix set, the value set in the basePath setting will be ignored.

    Default: true

  • stripPrefix

    Short Version
    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!

    Long Version
    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: false in 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.

    Default: true

Example

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 /topics to Kowl and enabled "StripPrefix" middleware
  • Kowl configured with the default settings
  • A user types the following address into their browser example.com/topics/topics/example-topic
  • 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 /topics in the X-Forwarded-Prefix header
  • The request reaches Kowl, which sees that X-Forwarded-Prefix is set and setBasePathFromXForwardedPrefix is true. So it tries to remove what it thinks is the prefix with the request path /topics/example-topic now becoming /example-topic
  • Kowl tries to find a handler for the route /example-topic but of course it won't find one.