Search the OSCAR Documentation
< All Topics
Print

Reverse Proxy

Updated
By Peter Hutten-CzapskiPeter Hutten-Czapski

Preface

A reverse proxy is a server that sits in front of web servers and forwards client (e.g. web browser) requests to those web servers. Reverse proxies are typically implemented to help increase security, performance, and reliability

These instructions provide direction to set up a reverse proxy behind which Tomcat/OSCAR will be protected. Nginx will handle the SSL, Tomcat will just need to server OSCAR content on port 8080.

These instructions are NOT fully tested.

Document Version History

v1.0 – Initial instructions for LTS Ubuntu 22.04 – Jan 12, 2023

Documentation Copyright © 2023 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

Purge Apache2

Because we will be using Nginx for this tutorial we need to first remove Apache if it is present

sudo apt-get purge apache2
sudo apt-get autoremove

Installing Nginx

Nginx is a light weight web server and will pass requests from outside the server and deliver them to OSCAR. Install it with

sudo apt install nginx

Now allow the nginx server you just installed to be accessed through your firewall. We will start with a http connection for testing.

sudo ufw allow 'Nginx HTTP'

Configuration for HTTPS

First you need a static ip with an attached fully qualified domain name (FQDN) eg one from Freenom

Then get certbot and the nginx plugin

sudo apt-get install certbot python3-certbot-nginx

Its good practice to set a server specific configuration file rather than editing the main configuration file. Assuming you own oscar.example.com that is what I would name the file for ease of reference. 

sudo nano /etc/nginx/sites-available/oscar.example.com

Type the following into the edit replacing oscar.example.com with your FQDN. Note that the server_name has to match exactly the FQDN so if you have a www. prefix include that.

upstream tomcat {
        server 127.0.0.1:8080 fail_timeout=0;
server {
        listen 443 ssl;
        ssl_certificate /etc/letsencrypt/live/oscar.example.com/fullchain.pem; 
        ssl_certificate_key /etc/letsencrypt/live/oscar.example.com/privkey.pem;
        include /etc/letsencrypt/options-ssl-nginx.conf;
        ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
        server_name oscar.example.com;
        client_max_body_size 4G;
        location / {
                include proxy_params;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_pass http://tomcat/;
                add_header 'Content-Security-Policy' 'upgrade-insecure-requests';
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_headers_hash_max_size 1024;
                proxy_headers_hash_bucket_size 128;
        }
}
server {
        if ($host = oscar.example.com) {
        return 301 https://$host$request_uri;
        } 
        listen 80;
        server_name oscar.example.com;
        return 404; 
}

To enable you need to create a link to the file and restart nginx:

sudo ln -s /etc/nginx/sites-available/oscar.example.com /etc/nginx/sites-enabled/
sudo systemctl restart nginx

The certificates referenced for the https will be created by Certbot. Certbot will connect to the FQDN on port 80 (http) and test if it can read an arbitrary file.

If your server is behind a router/firewalls you will need to open port 80 on your router and adjust your NAT to forward that port as port 80 on your server.  Those instructions vary by router.  For the ufw firewall you need to open http for Certbot and https for (eventually) OSCAR

sudo ufw allow 'Nginx HTTP'
sudo ufw allow 'Nginx HTTPS'

In the following replace oscar.example.com with your the fully qualified domain name that you own (if you have a www. prefix include that.)

sudo certbot --nginx -d oscar.example.com

Certbot looks for a server_name directive that matches the domain you request a certificate for and will configure the certificate if its not already in the above format.

Test by checking if there are files as below

sudo ls /etc/letsencrypt/live/FQDN
cert.pem  chain.pem  fullchain.pem  privkey.pem  README

The OSCAR Deb installer will install the certificate for you when it runs.

Restart nginx

sudo systemctl restart nginx

Now you can login to https://oscar.example.com/oscar

Table of Contents