KB: How to setup a custom domain


  • Used Zammad version: 3.2
  • Used Zammad installation source: (source, package, …): Debian 10
  • Operating system: Debian 10
  • Browser + version: Chrome latest

Expected behavior:

Actual behavior:

  • Instructions unclear.

Steps to reproduce the behavior:

Dear all

We try to set up the awesome knowledge base but we got stuck configuring the custom domain.
Our goal is to have the knowledge base under the domain “kb.your-domain.com”.

If we understand the documentation correctly we should add in zammad.conf around line 14 (just right after the server statement):

# Add following lines to "server" directive
if ($host = kb.your-domain.com ) {
  rewrite ^/(api|assets)/(.*)$ /$1/$2 last;
  rewrite ^(.*)$ /help$1 last;

and later around line 46 (into the location / statement)

# Add following line to "Location /" directive, before other proxy_set_header
proxy_set_header X-ORIGINAL-URL $request_uri;

So far so good, but how do we tell the server to listen to kb.your-domain.com too?

should this info be placed around line 22 in server_name?

(As you may notice we lack some nginx… ;-))

BR wucherpfennig

What we did so far:

since we use the same server but 2 different domains we copied the ngnix server configuration in order to use the right ssl certificate (we do not have wildcards defined).

The custom domain works regarding the KB shows up. Some issues persist:

  1. The directive with rewriting the route help seems not to work if you want to rewrite to a kb.your-domain directly.
    “Solution”: use as custom domain kb.your-domain.com/help and add the changes to zammad.conf according to the suggestions made by zammad.
  2. Using a custom domain results in not being able to see “internal” answers although the current user is logged in (as agent / admin).

As previously stated: any feedback is highly appreciated.

BR wucherpfennig

another conclusion:

  • If we enter a custom domain without subfolder and we get the nginx working then the KB logo will always try to link back to “/help” otherwise everything would work fine

We currently don’t have a working configuration solution on this.
I’m currently struggling greatly with time ressources whcih is why this topic is being delayed on my end.

I just wanted to point out (because I might loose track of this post), you can subscribe to this issue which I will update as soon as I have a solution. Promised!

Well, we got it somehow working:

  1. Enable KB
  2. Modify nginx to use server_name zammad.example.com kb.example.com;
  3. Add wildcard SSL certificates to Zammad nginx config
  4. Modify nginx again :wink: with something quirky like that:
   # "FIX": in order to NOT get redirected to #login route if accessing the kb @ kb.example.com 
   set $fullUrl  "$host$request_uri";

    if ($fullUrl = "kb.example.com/"){
        return 301 https://kb.example.com/help/de-de;

    # Add following lines to "server" directive
    if ($host = kb.example.com ) {
      rewrite ^/(api|assets)/(.*)$ /$1/$2 last;
      rewrite ^/help(.*)$ /help$1 last;
      #rewrite ^(.*)$ /help$1 last;
  1. Set in Zammad KB url as follows:

  1. Make the modifications suggest in the KB Zammad backend


Although it works somehow, there are some issues:

  1. Indication bar (draft, internal, public) will not be displayed
    • I assume this is related to the “catch” with the login route
  2. Opening KB from agents perspective does not work (it think there exists already a github issue)
1 Like

Just as a small follow up:
There’s now a rather bigger write up of configuration possibilities currently being tested and working.
The configurations in the linked comment will soon™ find their way into Zammad.

1 Like

This topic was automatically closed 120 days after the last reply. New replies are no longer allowed.