NGINX Reverse Proxy

Our linux server image version 221214 or later includes an nginx web server, acting as a reverse proxy in front of Blocks. Out of the box, it provides the following functionality:

Port Remapping

The reverse proxy re-maps ports as the traffic flows through it, thereby exposing HTTP to the outside world on the standard port 80, internally passing it on to Blocks on port 8080. Thus, when accessing Blocks from outside the virtual machine, you don't need to specify any port number.

Serving of Static Files

It serves all static files (those under /public), rather than passing those requests on to Blocks. Offloading such work leaves more headroom in Blocks for dealing with its more advanced functions.

HTTPS, Domain name and Certificate

The nginx reverse proxy can also manage a secure HTTPS connection, thus offloading also the work of encryption and decryption from Blocks. HTTPS is increasingly a requirement for many advanced web features. This applies also to Blocks, which is entirely web based. For instance, the Camera, QR Scanner and Locator (when using QR Code or GPS) block types may have limited or no functionality unless a secure HTTPS connection is used.

In order to use HTTPS to access Blocks, you need a number of additional things:

  • A domain name of your own.
  • A registrar managing that domain name on your behalf.
  • A DNS provider, making your domain name available on the internet.
  • A HTTPS Certificate (more on that below).

Furthermore, if you want to access your Blocks server from the internet, you'll also need connection from the internet to your Blocks server. This is often handled in your router or IT infrastructure, for example using a method known as port forwarding. Having your Blocks server accessible through the internet makes it easy for visitors to connect to Blocks using their mobile phones.

Obtaining a Certificate

You must obtain a HTTPS certificate from an accredited Certificate Authority (CA). Furthermore, since certificates expire after some time, you must renew your certificate on a regular basis. Fortunately, there's a relatively painless method available to do all of this from Let's Eencrypt. The server image comes with Let's Encrypt preinstalled, so once you've got your domain name registered with a DNS (you can check this using the nslookup terminal command), all you need to do is:

  1. Edit the nginx configuration file to specify your domain name, and restart nginx.
  2. Run Let's Encrypt's certbot command in the terminal, following its instructions.

To edit the nginx configuration file, do as follows:

  • Start the server.
  • Log in as the a user with administration permissions. On our Linux-based hardware server image, this is the pixi-admin user. If you're using our virtual server image (OVA file). that is the root user (accessed either through the virtualizers terminal window or over ssh, then switching to the root user using su).
  • Open the editor using the command sudo nano /etc/nginx/sites-available/blocks

The nano command opens a text editor, showing the configuration, that begins like this:

include /etc/nginx/snippets/pixi-expires.conf;
server {
    server_name _;

Replace the underscore character after server_name with your domain name, so it looks something like this but with your own domain name instead of mydomain.com):

include /etc/nginx/snippets/pixi-expires.conf;
server {
    server_name mydomain.com;

Make sure to keep the space after server_name as well as the semicolon after the domain name. Save the result by pressing ctrl-O followed by the Enter key, then exit the nano editor by ctrl-X.

Make sure you've set good, strong passwords on all your Blocks users. Finally, while still as the root user, run the following commands, pressing enter after each. The first of these commands checks your new nginx configuration for errors. Pay close attention to any error messages that may appear.

sudo /sbin/nginx -t
sudo systemctl restart nginx
sudo certbot --nginx

If the test is successful, then run the second command which restarts nginx to pick up the changed configuration. Finally, the last command tells the Let's Encrypt certbot to do its thing – obtaining a certificate for your domain, integrating it with nginx, etc. If all goes well, you should then be able to access your server from the internet using a URL like this (again using your own domain name):

https://mydomain.com/edit

Certbot will renew your certificate automatically before it expires. You can test automatic renewal for your certificates by running this command:

sudo certbot renew --dry-run

If you get stuck, and need more details, follow the official certbot guide found here, keeping in mind that all installations have already been done, so you can skip the first couple of steps.

If you want to use HTTPS for all traffic, edit the file at /etc/nginx/conf.d/pixilab.conf by uncommenting (removing the #-signs) the last section under "Redirect ALL http request to https", so the last section in that file looks like this:

# Redirect ALL http request to https
server {
    listen 80 default_server;
    server_name _;
    return 301 https://$host$request_uri;
}

Save and exit nano again, then test your configuration and restart nginx:

sudo /sbin/nginx -t
sudo systemctl restart nginx

Using Local Wifi

While you may use a local wifi network instead of making your Blocks server internet accessible, this adds more complexity for visitors in connecting to your system, since they must first connect to your local wifi and then to your blocks server. Both of these actions can be done from most modern smartphones using QR codes – but you will need two of those, and they need to be scanned in the right order. You of course also need to provide a wifi network with adequate performance and coverage. Thus, for most visitor-facing Blocks applications, internet access is the recommended method.

If you do opt for a local wifi network, your method for setting up HTTPS also becomes a bit more complicated:

  1. You must provide internet access to your visitors through your local wifi. This is required both to expedite the wifi connection (many phones will refuse to connect to a wifi that doesn't have internet access) and to access the DNS.
  2. Your DNS entry must point to the IP address of your intranet Blocks server, now (hopefully) accessible through your wifi. That means that any attempts to access it from the internet will fail (since it's only available while on the in-house wifi). An "official" DNS entry is required since many smartphones and browsers use some form of "secure DNS", such as DNS over HTTPS, and will ignore any in-house DNS.
  3. You can't use the automatic "certbot" method mentioned above to obtain a certificate. You must instead use a more complicated DNS-based method.