Skip to main content

NGINX Reverse Proxy Guide

info

This guide targets Windows and Linux (Debian-based) users.

Terminology​

  • API: The API of SnailyCAD - the backend.
  • Client: The client (UI) of SnailyCAD - the frontend.
  • NGINX: NGINX is a web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache.

1. Installing NGINX​

First, we need to install NGINX server on ur machine/server. To do this on Windows system, we download the latest version from (official site)[https://nginx.org/en/download.html]. If we use Linux we use apt package manager.

Click the url with the form of nginx/Windows-x.x.x (see the image below), this start the download of an .zip file.

nginx-download

Then extract the nginx-x.x.x.zip in C: drive and rename the dir from nginx-x.x.x to nginx. After that the nginx folder look like the image below.

extract-nginx

2. Starting NGINX​

To start NGINX you must open a command prompt or terminal and run the following command:

cd C:\nginx
nginx

If you have done everything correctly, you should be able to access the NGINX welcome page at http://localhost.

tip

Keep this command prompt open. You will need to run some more commands in this command prompt.

3. Configuring NGINX​

3.1. Setting client_max_body_size​

To allow for larger uploads, we must set this value to 100M. Open the C:\nginx\conf\nginx.conf (Windows) or /etc/nginx/nginx.conf (Linux) file and add the following code to the http block:

http {
  # ...
  client_max_body_size 100M;
  # ...
}
upload sizes

This will allow uploads up to 100MB. If you want to limit the upload size to a smaller size, you can change the value to something else. For example, 10M will limit the upload size to 10MB.

3.2. Setting server_names_hash_bucket_size​

To allow for longer domain names, we must set this value to 64. Open the C:\nginx\conf\nginx.conf (Windows) or /etc/nginx/nginx.conf (Linux) file and add the following code to the http block:

http {
  # ...
  server_names_hash_bucket_size 64;
  # ...
}
tip

A full example of the nginx.conf file can be found further down this page.

3.3. Configuring the API​

First, we need to configure the API. Open the C:\nginx\conf\nginx.conf (Windows) or /etc/nginx/nginx.conf (Linux) file and add the following code to the http block:

Make sure to replace the marked examples with your own values.

http {
  # ...

  # SnailyCAD API Reverse Proxy
  server {
    # Replace `example.com` with your domain name.
    server_name cad-api.example.com;

    location / {
      proxy_pass http://localhost:8080; # The API port of SnailyCAD's API (Default: 8080)
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host $host;
      proxy_cache_bypass $http_upgrade;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }


    # Security headers
    add_header X-XSS-Protection          "1; mode=block" always;
    add_header X-Content-Type-Options    "nosniff" always;
    add_header Referrer-Policy           "no-referrer" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-DNS-Prefetch-Control on;
    add_header Cross-Origin-Resource-Policy "cross-origin";

    # keep this as-is unless you know what you're doing.
    # for SSL, see step 6
    listen 80;
  }

  #...
}
tip

A full example of the nginx.conf file can be found further down this page.

3.4. Configuring the client​

Once the API is configured, we must add the client block. Open the C:\nginx\conf\nginx.conf (Windows) or /etc/nginx/nginx.conf (Linux) file and add the following code to the http block:

Make sure to replace the marked examples with your own values.


http {
  # ...

  # SnailyCAD Client Reverse Proxy
  server {
    # Replace `example.com` with your domain name.
    server_name cad.example.com;

    location / {
      proxy_pass http://localhost:3000; # The API port of SnailyCAD's client (Default: 3000)
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host $host;
      proxy_cache_bypass $http_upgrade;
    }


    # Security headers
    add_header X-XSS-Protection          "1; mode=block" always;
    add_header X-Content-Type-Options    "nosniff" always;
    add_header Referrer-Policy           "no-referrer" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-DNS-Prefetch-Control on;
    add_header Cross-Origin-Resource-Policy "same-site";

    # keep this as-is unless you know what you're doing.
    # for SSL, see step 6
    listen 80;
  }

  # ...
}
tip

A full example of the nginx.conf file can be found below.

Complete example `nginx.conf` file

#user  nobody;
worker_processes  1;

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;
    server_names_hash_bucket_size 64;
    client_max_body_size 100M;

    sendfile        on;
    keepalive_timeout  65;
    gzip  on;

    # SnailyCAD API Reverse Proxy
    server {
      # Replace `example.com` with your domain name.
      server_name cad-api.example.com;

      location / {
        proxy_pass http://localhost:8080; # The API port of SnailyCAD's API (Default: 8080)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
      }


      # Security headers
      add_header X-XSS-Protection          "1; mode=block" always;
      add_header X-Content-Type-Options    "nosniff" always;
      add_header Referrer-Policy           "no-referrer" always;
      add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
      add_header X-DNS-Prefetch-Control on;
      add_header Cross-Origin-Resource-Policy "cross-origin";

      # keep this as-is unless you know what you're doing.
      listen 80;
    }


    # SnailyCAD Client Reverse Proxy
    server {
      # Replace `example.com` with your domain name.
      server_name cad.example.com;

      location / {
        proxy_pass http://localhost:3000; # The API port of SnailyCAD's client (Default: 3000)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
      }


      # Security headers
      add_header X-XSS-Protection          "1; mode=block" always;
      add_header X-Content-Type-Options    "nosniff" always;
      add_header Referrer-Policy           "no-referrer" always;
      add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
      add_header X-DNS-Prefetch-Control on;
      add_header Cross-Origin-Resource-Policy "same-site";

      # keep this as-is unless you know what you're doing.
      listen 80;
    }

    server {
        listen       80;
        server_name  localhost;

        location / {
            root   html;
            index  index.html index.htm;
        }

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }
}

3.5 Verify NGINX configuration​

To verify the NGINX configuration, run the following command:

cd C:\nginx
nginx -t

If the configuration is valid, you should see the following output:

nginx: the configuration file C:\nginx\conf\nginx.conf syntax is ok
nginx: configuration file C:\nginx\conf\nginx.conf test is successful

3.6. Restarting NGINX​

To update the running nginx with new config, run the following command:

cd C:\nginx
nginx -s reload
tip

This command must be run every time you make changes to the nginx.conf file in the C:\nginx (Windows) or /etc/nginx (Linux) directory.

4. Updating SnailyCAD configuration​

You must now update your SnailyCAD instance configuration to use the domain. To do this, open your SnailyCAD instance .env file:

# This is the URL to your site where the CAD is hosted.
CORS_ORIGIN_URL="http://cad.example.com"

# This is the URL to your site where the CAD is hosted.
NEXT_PUBLIC_CLIENT_URL="http://cad.example.com"

# The URL to where the API is hosted.
NEXT_PUBLIC_PROD_ORIGIN="http://cad-api.example.com/v1"

# The domain of your site. Without any subdomains or paths.
DOMAIN="example.com"
info

Now SnailyCAD is running behind NGINX. You can now access SnailyCAD by visiting http://cad.example.com with the API accessible via http://cad-api.example.com.

5. Starting NGINX on boot​

To start NGINX when the system is restarted you will need to add a task to the Task Scheduler or systemd (Linux), which will run the NGINX automatically for you.

To achieve this on Windows, create a file with name start.bat inside C:\nginx directory and add the following code.

@ECHO OFF
REM Start Nginx
tasklist /FI "IMAGENAME eq nginx.exe" 2>NUL | find /I /N "nginx.exe">NUL
IF NOT "%ERRORLEVEL%"=="0" (
   REM Nginx is NOT running, so start it
   start nginx
   ECHO Nginx started.
) else (
   ECHO Nginx is already running.
)

Once you have added the file you'll need to open Task Scheduler and add a new task. You can follow the steps below to add this task:

  1. Open Task Scheduler, and in the Task Scheduler Library you will want to click Create Task... from the menu on the right, or buy right clicking on the folder.
  2. Give it a name like Start NGINX, and select 'Run whether user is logged on or not'.
  3. Click the Triggers tab.
    1. Make a new trigger and in the top drop down select At startup.
    2. Tick Repeat task every: and set it to 5 minutes.
    3. Click 'OK'.
  4. Click the Actions tab.
    1. Make a new action and select Start a program from the top drop down.
    2. Browse to where the batch script was saved, which should be C:\nginx\start.bat.
    3. Click OK.
  5. You can now click OK at the bottom os the task and you will need to enter the details of the user the task will run under, this should be the same account that NGINX will be running under.
info

This task will check every 5 minutes to see if NGINX is running, and if it is not it will start a new instance of NGINX.

6. Firewall​

To secure your server we recommend to enable firewall, to do that following the instructions below.

The first time you run the nginx, opens a window and ask you to give NGINX firewall access.

7. SSL​

To enable SSL on Windows or Linux system we have to download some tools.

7.1. Installing tools​

To enable SSL on Windows system, we will use win-acme tool, to generate our SSL certificates.

Download the latest release of win-acme from here (filename: win-acme.<version>.x64.pluggable.zip). Once downloaded, extract the archive (.zip) to C:\win-acme and open wacs.exe.

7.2. Generating SSL certificates​

Once you have opened wacs.exe, you should see the following screen:

win-acme

  1. Press M (Create certificate (full options)) then Enter to create a new certificate. You should now see the following screen:

win-acme

  1. Press 2 (Manual Input) then Enter. You should now see the following screen:

win-acme

  1. Enter the domains required for your SnailyCAD instance. For example, your client and API URL: cad.example.com, cad-api.example.com.

  2. Press Enter to continue. You should now see the following screen:

win-acme

  1. Press 2 (Separate certificate for each host (e.g. sub.example.com)) then Enter. You should now see the following screen:

win-acme

  1. Press 6 ([dns] Create verification records manually) then Enter.

  2. Press 2 (RSA Key) then Enter. You should now see the following screen:

win-acme

  1. Press 2 (PEM encoded files (Apache, nginx, etc.)) then Enter. It will now ask you to enter the path to where you want to store the certificate. For example, C:\ssl. Press Enter to continue.

  2. Press 1 (None) then Enter. It may ask you for additional steps, press 5 (No additional steps) then Enter. It may also ask you for an installation step, press 3 (No additional installation steps) then Enter.

  3. It should now ask you to accept the terms of service. Press y then Enter to accept the terms of service. It should now generate the SSL certificate. Once it has finished, you should see the following screen:

win-acme

  1. Important: You must now add the DNS records to your domain. For example, if you are using Cloudflare, you must add the DNS records to Cloudflare. Once you have added the DNS records, press Enter to continue.

  2. Continue following the prompts until it successfully generates the SSL certificate.

  3. You can now close wacs.exe.

7.3. Configuring NGINX for SSL​

Once you have generated the SSL certificate, you must now configure NGINX to use the SSL certificate. Open the C:\nginx\conf\nginx.conf file and add or update the following code to both server blocks:

# ...
server {
  # ...

  # Previous was `listen 80;`:
  listen 443 ssl http2;

  # Add the following lines:
  ssl_certificate C:/ssl/xxxxxxxxxxxxx-chain.pem; # The path to your SSL certificate (-chain.pem file)
  ssl_certificate_key C:/ssl/xxxxxxxxxxxxx-key.pem; # The path to your SSL certificate key (-key.pem file)
  ssl_session_timeout 5m;

  # ...
}

# ...
HTTPS:// REDIRECT

You can also add a redirect from http:// to https://, by adding the following code to a new server block:

server {
  listen 80 default_server;
  listen [::]:80 default_server;
  server_name _;

  return 301 https://$host$request_uri;
}

7.4. Verify NGINX configuration​

To verify the NGINX configuration, run the following command:

cd C:\nginx
nginx -t

If the configuration is valid, you should see the following output:

nginx: the configuration file C:\nginx\conf\nginx.conf syntax is ok
nginx: configuration file C:\nginx\conf\nginx.conf test is successful

7.5. Restarting NGINX​

To update the running nginx with new config, run the following command:

cd C:\nginx
nginx -s reload
tip

This command must be run every time you make changes to the nginx.conf file in the C:\nginx (Windows) or /etc/nginx (Linux) directory.

8. Updating SnailyCAD configuration​

You must now update yout SnailyCAD instance configuration to use the SSL certificate. To do this, stop any running SnailyCAD instance (if exist), open your SnailyCAD instance .env file and change the following:

# This is the URL to your site where the CAD is hosted.
CORS_ORIGIN_URL="https://cad.example.com"

# This is the URL to your site where the CAD is hosted.
NEXT_PUBLIC_CLIENT_URL="https://cad.example.com"

# The URL to where the API is hosted.
NEXT_PUBLIC_PROD_ORIGIN="https://cad-api.example.com/v1"

# The domain of your site. Without any subdomains or paths.
DOMAIN="example.com"
tip

Replace example.com with your domain name.

tip

You can now access SnailyCAD via https://cad.example.com with the API accessible via https://cad-api.example.com.

Troubleshooting​

If you are having issues with NGINX, you can check the NGINX logs.

To enable nginx logs, edit C:\nginx\conf\nginx.conf file and uncomment the following line:

error_log  logs\error.log;
tip

Reload the NGINX instance to enable error logging. After that check the error.log file inside C:\nginx\logs.

Was this page helpful?

Happy React is loading...
Last updated on