---
title: "Nginx server - Subfolder hosting for your site"
slug: "nginx-server"
description: "Nginx is an open-source web server.To know more, visit the To set up a sub folder/subdirectory Add the following location blocks in your Nginx configuration file /etc/nginx/default."
tags: ["Custom domain", "sub directory hosting"]
updated: 2026-06-02T13:57:57Z
published: 2026-06-02T13:57:57Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nginx server - Subfolder hosting

pubTo host your Document360 knowledge base in a subfolder (such as `example.com/docs`) using the Nginx server, specific configurations are required. This article guides you through enabling the required modules, configuring proxy and rewrite rules, and managing paths for articles, APIs, and sitemaps. It also explains how to handle URL redirection properly to avoid duplicate content issues in search engines.

To learn more about Nginx, visit the [Nginx documentation](https://nginx.org/en/docs/).

---

## Setting up a subfolder/subdirectory

**Example:**

> [!NOTE]
> ** NOTE
> 
> Replace the example domain with your own document360 provided domain/custom domain.
> 
> - Example domain represented using `example.document360.io`
> - Subfolder/subdirectory path (/docs) represented as `example.document360.io/docs`

1. Add the following location blocks in your Nginx configuration file (`/etc/nginx/default`).

```nginx
location /docs {
    proxy_pass https://example.document360.io/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}
```

1. Restart the Nginx web server
2. For example, if you are using Nginx on Linux, then use the command `$ sudo systemctl restart nginx`

> [!NOTE]
> ** NOTE
> 
> If you are on KB Site 2.0 and wish to host your Knowledge base as a subfolder, you must define both:
> 
> - The **Subfolder path** (e.g., `/docs`, `/help`)
> - The **Site API path** (e.g., `/api`, `/docs-api`)
> 
> After setting these values, you must also configure corresponding `location` blocks in your web server to proxy both UI and API traffic. You can find the API configuration example in the section below.

---

### Using a custom subfolder/subdirectory path

- You can set up your knowledge base on subdirectory paths other than `/docs`. For example, `/help`, `/support`, etc.
- When setting up other paths, add the languages associated with each Workspace.
- Add a few more lines to achieve this. Restart the server once done.

**Example:**

> [!NOTE]
> ** NOTE
> 
> Replace the Document360 provided domain and the subdirectory domain with your own domains. Also, replace the workspace name, subfolder path, and language with your requirements.
> 
> - Document360 provided domain represented as `example.document360.io`
> - Workspace name represented as `/v1/`
> - Subfolder path represented as `/help/`
> - Language represented as `/he` for Hebrew.

```nginx
location /help {
    proxy_pass https://example.document360.io/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
```

#### Removing the workspace slug from internal links

If required, you can remove workspace slugs from internal links at the NGINX reverse proxy level using `sub_filter` rules.

Example:

```nginx
sub_filter "/Version_slug/docs/" "/help/";
```

This rewrites workspace-specific paths before they are served to users.

Use this approach only if your site structure requires workspace-agnostic URLs.

---

### Why `proxy_set_header Accept-Encoding ""` is required

When hosting a Document360 knowledge base in a custom subfolder (for example, `/help`), NGINX commonly uses `sub_filter` to rewrite internal URLs such as `/docs` to `/help`.

By default, the upstream server (Document360) may return gzip-compressed HTML. NGINX cannot apply****`sub_filter` rules on compressed responses.

This leads to the following issues:

- Internal links are not rewritten
- Home page widgets continue to point to `/docs`
- Category cards and navigation routes break

To ensure URL rewriting works correctly, you must disable compression from the upstream server by adding the following directive:

`proxy_set_header Accept-Encoding "";`

This setting:

- Forces Document360 to return uncompressed HTML
- Allows all `sub_filter` rules to execute correctly
- Ensures paths such as `/docs/en/` are rewritten to `/help/en/`

This setting is required whenever****`sub_filter`****is used.

---

### Mandatory API path configuration for KB Site 2.0

If you are on [**KB Site 2.0**](/help/docs/knowledge-base-site-20), you are required to define a **Custom Site API path** and must add a corresponding `location` block in your NGINX configuration.

This ensures API requests are correctly routed to Document360 and prevents issues such as redirect loops or broken API calls.

Here’s an example using `/api` as the Site API path:

```nginx
location /api {
    proxy_pass https://example.document360.io/api;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name on;
    proxy_set_header Accept-Encoding "";

    sub_filter_types *;
    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
```

> [!NOTE]
> ** NOTE
> 
> Replace `/api` and `/docs-api` with the exact values configured under **Site API path** in the Document360 portal.

Once you have added both `location` blocks, restart the Nginx web server. For example, if you are using Nginx on Linux, then use the command `$ sudo systemctl restart nginx`.

Use `sub_filter_types *;` only when rewriting HTML or API responses that may return non-HTML content. Avoid using it unless URL rewriting is required.

---

### When to use `sub_filter` in the API location block

Adding `sub_filter` rules in the API location block is not always required.

Use `sub_filter` in the API location block only when:

- Your UI path is rewritten (for example, `/docs` → `/help`)
- API responses contain embedded `/docs` paths that must be rewritten

If your project continues to use `/docs` as the UI path, do not add****`sub_filter`****rules to the API block.

> [!TIP]
> **IMPORTANT** If your domain already uses `/api` for another application, you must update the Site API Path in the Document360 portal to a different value (for example, `/docs-api`) and use the same path in your NGINX configuration.
> 
> The API path configured in the portal and the NGINX location block must match exactly.

---

### To enable the workspaces dropdown

If you want to enable the workspace dropdown navigation for your project when you host it in a custom subdirectory and path, add the following code for each of the workspaces available in your project.

**Example:**

Let's assume your project has two workspaces, **v1** and **v2**. In that case, you must add two code blocks, one for each Workspace.

> [!NOTE]
> ** NOTE
> 
> Replace the Document360 provided domain and the subdirectory domain with your own domains. Also, replace the workspace name, subfolder path, and language with your requirements.
> 
> - Document360 provided domain represented as `example.document360.io`
> - Workspace name represented as `/v1/`,`/v2/`
> - Subfolder path represented as `/help/`
> - Language represented as `/he` for Hebrew.

```nginx
location /v2/help {
    proxy_pass https://example.document360.io/v2/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v2/docs/" "v2/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
-----------------------------------------------------
location /v1/help {
    proxy_pass https://example.document360.io/v1/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
-----------------------------------------------------
location = /v2/docs {
    return 301 /v2/help;
}
-----------------------------------------------------
location = /v1/docs {
    return 301 /v1/help;
}
```

> [!NOTE]
> ** NOTE
> 
> If you want your readers to navigate between the different public workspaces of your project from the dropdown (on mouse click), add the location block for all available workspaces.

1. Restart the Nginx web server
2. For example, if you are using Nginx on Linux, then use the command `$ sudo systemctl restart nginx`

---

## Helpful Links

Here are a few external links that may help you understand the Nginx server **location blocks** in detail:

- [NGINX Docs: Configuring NGINX and NGINX Plus as a Web Server](https://docs.nginx.com/nginx/admin-guide/web-server/web-server/)
- [DigitalOcean: Understanding Nginx Server and Location Block Selection Algorithms](https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms)

---

## Sitemap generation

**Example:**

> [!NOTE]
> ** NOTE
> 
> Replace the example domain with your own document360 provided domain/custom domain.
> 
> - Example domain represented using `example.document360.io`
> - The sitemap prefix remains the same except for the language code (en, fr, de, etc.) `example.document360.io/sitemap.xml.en`

```nginx
location /sitemap.xml.en {
    proxy_pass https://example.document360.io/sitemap.xml.en;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
    proxy_set_header Accept-Encoding "";

    sub_filter_types text/xml;
    sub_filter "https://www.example.document360.io/docs/" "https://www.example.document360.io/help/";
    sub_filter_once off;
 }
```

---

## Home page hosted on a subfolder

To host your project's home page on a custom subdirectory/subfolder path, add the following code for each of the home page workspaces available in your project.

**Example:**

Let's assume your project has two workspaces, **V1** and **V2**. In that case, you must add two code blocks, one for each Workspace.

> [!NOTE]
> ** NOTE
> 
> Replace the Document360 provided domain and the subdirectory domain with your own domains. Also, replace the workspace name, subfolder path, and language with your requirements.

- Document360 provided domain represented as `example.document360.io`
- Workspace name represented as `/v1/`,`/v2/`

```nginx
location =/v1 {
    proxy_pass https://example.document360.io/;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

location =/v2 {
    proxy_pass https://example.document360.io/;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

location /v1/en {
  return 301 /v1;
}

location /v2/en {
  return 301 /v2;
}
```

> [!WARNING]
> ** PRO TIP
> 
> The equal sign can be used if the location needs to match the exact request URI. When this modifier is matched, the search stops right here. For more information, [**click here**](https://docs.nginx.com/nginx/admin-guide/web-server/web-server/#locations)**.**
> 
> **Example:**`location =/help {`

1. Restart the Nginx web server
2. For example, if you are using Nginx on Linux, then use the command `$ sudo systemctl restart nginx`

**Knowledge base site home page**

The default home page for a knowledge base site appears at the root directory (For example, `example.document360.io`). If the project contains a Workspace and language-specific home page, the slug following the root directory would be /<workspace_name>/<language_code>. (For example,`example.document360.io/v2/he`)

---

## What happens next?

Once you have successfully configured the web server, your knowledge base site is live on your custom subfolder/subdirectory. However, the existing URL for your project will serve the requests.

> **For example,** `example.document360.io` and `example.com/docs` (if `/docs` is your folder path) will point to the knowledge base site.

This may cause duplicate content in search engines (Google, Bing, etc.). To prevent this, a redirect from the Document360 project subdomain to your custom domain will be required.

> [!NOTE]
> ** NOTE
> 
> To prevent duplicate content, enable the **Restrict subdomain access** toggle under **Settings > Knowledge base site > Custom domain > Subfolder hosting**. Ensure a canonical domain is configured before enabling this. Once enabled, your Document360 subdomain will automatically redirect to your canonical domain.

---

## Canonical URL for Subfolder Hosting

When hosting your knowledge base in a subfolder, you must configure a **canonical URL** to ensure search engines index your **custom domain and subfolder path**, not the default `*.document360.io` domain.

This prevents duplicate indexing and improves SEO performance.

### How to set the canonical URL

1. Go to **Settings > Knowledge base site > Custom domain > Subfolder hosting**.
2. Enter the full subfolder URL (for example, `https://example.com/help`).
3. Click **Save**.

Once configured, search engines will treat the subfolder URL as the primary source for indexing.

---

## Troubleshooting

This section provides step-by-step guidance to troubleshoot common challenges you may face during the NGINX setup process. From subfolder hosting issues to failed configuration tests, each solution is designed to help you quickly identify and resolve potential roadblocks, ensuring a smooth and efficient server configuration.

### Resolving invalid location directive in NGINX

**Error:**nginx: [emerg] "location" directive is not allowed here

This error occurs when a location directive is placed outside its valid context, such as outside the server block. In NGINX, location blocks must be defined within a server block.

**Steps to resolve:**

1. Ensure that the location block is placed correctly within the server block. Refer to the below sample block:

```nginx
server {
    listen 80;
    server_name example.com;
    location /docs {
        proxy_pass https://example.document360.io/docs;
        proxy_set_header Host example.document360.io;
    }
}
```
2. To avoid this issue, do not place location directives in the global `http` context or outside the `server` context.
3. If the issue persists after following these steps, please contact the Document360 support team for further assistance: [Contact Document360 Support](https://document360.com/support/)

### Certbot package availability issue

**Error:** No package Certbot available

This issue often occurs when the EPEL repository (required for Certbot installation on RHEL-based distributions) is not enabled, or the package manager is unable to locate Certbot on RHEL-based distributions.

**Steps to resolve:**

1. Enable the EPEL repository by using the code below:

```nginx
sudo yum install epel-release
```
2. Update the repository cache and try installing Certbot again by using the code below:

```nginx
sudo yum install certbot
```
3. Ensure your instance has internet access to fetch the repository files. If the problem persists, verify the repository configuration files in `/etc/yum.repos.d/`.
4. If the issue persists after following these steps, please contact the Document360 support team for further assistance: [Contact Document360 Support](https://document360.com/support/)

### NGINX configuration test issue

**Error:** NGINX configuration test failed

This issue occurs when there is a syntax error in the NGINX configuration file.

**Steps to resolv**e:

1. Run the configuration test command:

```nginx
sudo nginx -t
```
2. Review the error message and the line number, like the example shown below:

```nginx
nginx: [emerg] invalid parameter "proxy_pas" in /etc/nginx/sites-enabled/example:22
nginx: configuration file /etc/nginx/nginx.conf test failed
```
3. Open the specified file `/etc/nginx/sites-enabled/example` and fix the configuration issue. For example:

```nginx
# Incorrect
proxy_pas https://example.com;

# Correct
proxy_pass https://example.com;
```
4. Once the configuration issue is fixed, restart NGINX:

```nginx
sudo systemctl restart nginx
```
5. If the issue persists after following these steps, please contact the Document360 support team for further assistance: [Contact Document360 Support](https://document360.com/support/)

### SSL certificate issue

**Error:** SSL certificate not working

This issue may occur due to an incorrect NGINX SSL configuration or when there is an issue with the installed certificate. The certificate details, such as domain and expiry date, might not match the configuration details.

**Steps to resolve:**

1. Verify the certificate files by using the code below:

```nginx
openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -text -noout
```
2. Ensure that your configuration matches the certificate details, such as the domain and expiry date.
3. Ensure the NGINX SSL configuration is correct. Refer to the code below as an example:

```nginx
server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
}
```
4. Once done, restart NGINX using the code below:

```nginx
sudo systemctl restart nginx
```
5. If the issue persists after following these steps, please contact the Document360 support team for further assistance: [Contact Document360 Support](https://document360.com/support/)

---

### FAQ

#### Why is my site's home page not available?

Once you have designed the project’s home page in the site builder, ensure you publish it. Confirm the home page is live and accessible to the intended audience.

#### Why are my home page widgets and category links redirecting to `/docs` instead of `/help`?

This issue occurs when NGINX `sub_filter` rewriting is not applied.

The upstream server (Document360) may return gzip-compressed HTML, and NGINX cannot perform `sub_filter` replacements on compressed responses. As a result, `/docs` paths inside the HTML are not rewritten, causing home page widgets and category cards to route incorrectly.

#### How to fix it

Force the upstream server to return uncompressed HTML by adding the following directive to the relevant location block:

```nginx
proxy_set_header Accept-Encoding "";
```

This ensures:

- HTML responses are uncompressed
- `sub_filter` rules execute correctly
- Internal links route to the correct subfolder path

## Related

- [Hosting Document360 on a subfolder](/document360-on-a-sub-folder.md)