Nginx server - Subfolder hosting

Nginx is an open-source web server. To know more, visit the Nginx documentation

Setting up a subfolder/subdirectory

Example:

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).

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;
}

2. Restart the Nginx web server

3. For example, if you are using Nginx on Linux, then use the command
   $ sudo systemctl restart nginx

NOTE

If you are on KB Site 2.0 and wish to host your Knowledge base as a subfolder, you have to define the Subfolder path as well as the Site API path.

To setup on other than '/docs' 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.

• A few more lines need to be added to achieve this. Restart the server once done.

Example:

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.

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;
}

1. Restart the Nginx web server

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

To enable the workspaces dropdown

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

Example:

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

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.

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

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

• DigitalOcean: Understanding Nginx Server and Location Block Selection Algorithms

Sitemap generation

Example:

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

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;

Home page hosted on a subfolder

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

Example:

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

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/

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;
}

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.

Example: location =/help {

2. Restart the Nginx web server

3. For example, if you are using Nginx on Linux, then use the command
   $ sudo systemctl restart nginx

Knowledge base site home page

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.). A redirect from the Document360 project sub-domain to your custom domain will be required to prevent this.

NOTE

To enable the redirect from example.document360.io to example.com/docs, please contact us at support@document360.com.

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:

   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

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 below code:

   sudo yum install epel-release

2. Update the repository cache and try installing Certbot again by using the below code:

   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

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 resolve:

1. Run the configuration test command:

   sudo nginx -t

2. Review the error message and the line number like the example shown below:

   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:

   # Incorrect
   proxy_pas https://example.com;
   
   # Correct
   proxy_pass https://example.com;

4. Once the configuration issue is fixed, restart 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

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 below code:

   openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -text -noout

2. Ensure that your configuration matches the certificate details, such as domain and expiry date.

3. Ensure the NGINX SSL configuration is correct. Refer to the below code as an example:

   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 below code:

   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