Menu

Reverse proxy guide for qTest OnPremise with Nginx

Following this guide to deploy Nginx as a reverse proxy that provide SSL termination for your qTest Applications, include qTest Manager, qTest Sessions, qTest Insights and qTest Parameters.

Install

Install Nginx on a Linux system

We can either install it as a Linux Package or build it from source by following the instruction in http://nginx.org/en/linux_packages.html

Install Nginx as a Windows Service

  1. Follow the instruction at http://nginx.org/en/docs/windows.html to initially setup Nginx on the server (it is not ready for use, yet!). Suggest to use a Stable version, which is 1.12.2 at the time this article is written
  2. As we have Nginx setup successfully and can access it default web page at "localhost" (Nginx use port 80 by default, may run into port confliction and crash upon startup if there are already another service occupy port 80 on the server)

    NOTE: In case we need to change Nginx to use a different port, we can alter the configuration inside "nginx-1.12.1\conf\nginx.conf". Change the default "listen 80" to a different value. For example: "listen 10080"

    2.png

  3. If we use "start nginx.exe" on the Command Prompt to start Nginx, we would expect to see its processes tree like below

    NOTE: To be able to display the processes of the system in a tree view form like showing in the screenshot, you should use Process Explorer (download link) from Microsoft

    3.png

  4. Once confirm everything is working as expect, proceed to stop Nginx (so we can set it running as a Windows service later on). We would expect to see all nginx.exe processes get terminated at this point

    4.png

  5. Download the Windows Service component at https://nssm.cc/download. We can use the latest version, which is 2.24 at the moment this article was written
  6. Use the 64 bit binary of NSSM to execute the command "nssm install nginx". Make sure the Command Prompt is being run under Administrator privilege

    NOTE: In case you want to modify the service configuration later on, use command "nssm edit nginx"

    6.png

  7. On the NSSM service installer dialog, proceed to fill out the information
  8. In the Application tab, make sure Path is pointing to the directory where we have Nginx extracted earlier

    8.png

  9. In the I/O tab, make sure the Input (stdin) value is "start nginx" and the location of the Output and Error is set to a place where we know how to access

    9.png

  10. Once set, click Install service, to Finish. If everything goes right, we should see a successful prompt

    10.png

  11. The service won't be started automatically so we have to go into Windows Service Manager to finish the rest

    11.png

  12. If the service is started correctly, we should be able to access its default web page again at "localhost", and its process tree should also look like below

    12.png

  13. In case the service fails to start and we can't access its default web page via "localhost", we should check out the 2 log files we have specified previously during the service installation to find out the cause

    NOTE: Other service log e.g. access log can also be checkout inside %NGINX_HOME%/logs

  14. Try stopping the Windows Service and access "localhost" again. We would expect to received an error message like below (make sure browser cache has been clean or disabled)

    14.png

  15. An extra step here would be to reboot the server to see if the service can come back online automatically or not

Configure Nginx to terminate SSL for qTest applications

Before you start

  • Make sure you have your SSL certificate in PEM format (including its private key file) ready on the server
  • You should contact your IT department for those certificate files or get one from any Certificate Authority (CA) of your choice

Configure

  1. Inside Nginx installation folder, go into the "conf" folder and modify nginx.conf file
  2. Clean up all default configuration and copy the below configuration snippet in there

    Please note that the provided configuration is based on an assumption that:

    • You are still serving end user HTTP traffic over port 80, which is redirected by default to HTTPS in port 443
    • Your end user can access HTTPS via port directly if they don't want to be redirected from HTTP
    • The HTTPS connection will use the SSL/TLS certificate stored in c:/.ssh/server.crt with an accompany private key at c:/.ssh/server.key
    • Your qTest Manager is running on the same host at port 8080. Its proxied HTTPS port would be 443
    • Your qTest Sessions is running on the same host at port 9080. Its proxied HTTPS port would be 9443
    • Your qTest Insights is running on the same host at port 10080. Its proxied HTTPS port would be 10443
    • Your qTest Parameters is running on the same host at port 11080. Its proxied HTTPS port would be 11443

    Please change the value in your configuration to match with the actual setup you have on your host

    NOTE:

    • System variables: Inside the template configuration, anything that started with a $ character is a system variable which will be populated automatically by Nginx itself, we don't need to replace them
    • Clustering deployment: In case you are deploying your qTest applications across different servers, you should install and configure separate Nginx instance on each application server. The configuration should only include the part of a specific application running on that server and don't need to include anything else
    events {
    }
     
    http {
     
    #### Generic configuration applied for all applications ####
      client_max_body_size 0;
      access_log  off;
      proxy_read_timeout 600s;
      proxy_send_timeout 600s;
     
    #### For qTest Manager ####
      upstream qtest {
        server 127.0.0.1:8080;
      }
      map $http_host $qtest_host {
        default $http_host;
        ~^(?.*):(.*)$ $h;
      }
      server {
        listen 80;
        return 301 https://$qtest_host:443$request_uri;
      }
      server {
        listen 443 ssl;
        ssl_certificate c:/.ssl/server.crt;
        ssl_certificate_key c:/.ssl/server.key;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
     
        location / {
          proxy_pass http://qtest;
          proxy_redirect http://$http_host $scheme://$http_host;
          proxy_set_header Host $http_host;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          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 X-Forwarded-Host $http_host;
        }
      }
     
    #### For qTest Sessions ####
      server {
        listen 9443 ssl;
        ssl_certificate c:/.ssl/server.crt;
        ssl_certificate_key c:/.ssl/server.key;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
     
        location / {
          proxy_pass http://127.0.0.1:9080;
          proxy_redirect http://$http_host $scheme://$http_host;
          proxy_set_header Host $http_host;
          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 X-Forwarded-Host $http_host;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
        }
      }
     
    #### For qTest Insights ####
      server {
        listen 10443 ssl;
        ssl_certificate c:/.ssl/server.crt;
        ssl_certificate_key c:/.ssl/server.key;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
     
        location / {
          proxy_pass http://127.0.0.1:10080;
          proxy_redirect http://$http_host $scheme://$http_host;
          proxy_set_header Host $http_host;
          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 X-Forwarded-Host $http_host;
        }
      }
     
    #### For qTest Parameters ####
      server {
        listen 11443 ssl;
        ssl_certificate c:/.ssl/server.crt;
        ssl_certificate_key c:/.ssl/server.key;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
     
        location / {
          proxy_pass http://127.0.0.1:11080;
          proxy_redirect http://$http_host $scheme://$http_host;
          proxy_set_header Host $http_host;
          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 X-Forwarded-Host $http_host;
        }
      }
     
    }		
    		
  3. Save the new configuration and then restart Nginx service for the change to take effect. Now your application should be served over HTTPS by the Nginx service. If you are following our default configuration all the way, your qTest applications can be accessed at:

    • qTest Manager: https://<hostname>
    • qTest Sessions: https://<hostname>:9443
    • qTest Insights: https://<hostname>:10443
    • qTest Parameters: https://<hostname>:11443
  4. Now login to qTest Manager and go the Site Administrator > System Configuration and change all the URL configuration in there to use the one that is being served by the reverse proxy
Powered by Zendesk