In order to publish your Portrait instance to the web, you need a reverse proxy. We got the best results using nginx. Furthermore, we used certbot for activating a free and simple to use TLS/SSL encryption. This article will present you an example configuration for nginx, explain how to use certbot and provide a small troubleshooting section if problems should arise.

You can use your existing reverse proxy setup, but keep in mind, that you have to enable web sockets and take care of SSL/TLS on your own.

Reference setup

The following chapters explain how the setup with nginx and certbot is done.

In our example, Portrait will be accessed via https://portrait.customer.com and portrait is running on a different host 192.168.1.99 on port 80. We use CentOS for our proxy server.

Install nginx

To install nginx, a few commands are needed:

# Connect to your Linux server with SSH
# User and password needed

# First, we update all server components
# If some components are upgradable, do it
sudo apt update

# Then, we install nginx
sudo apt install nginx

Configuring nginx

After you installed nginx, you need to configure your site. Depending on your host operating system, the location of the config folder can vary. On CentOS, the config folder is at: /etc/nginx/conf.d.

Create a new file, e.g., with vi: vi portrait.customer.com.conf or with nano:

cd /etc/nginx/conf.d
sudo touch portrait.customer.com.conf

sudo nano portrait.customer.com.conf
# Import the config from next step with right mouse click
# Save the file with CTRL+S
# Exit nano editor with CTRL+X

The file name is the address of your portrait instance + .conf as file prefix.

Copy the following content to your file:

server {

  location / {
    proxy_pass http://192.168.1.99:80;
    proxy_buffering off;
    proxy_set_header X-real-IP $remote_addr;
    proxy_pass_request_headers on;
    proxy_pass_request_body on;

    # proxy web sockets
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection upgrade;
    proxy_set_header Accept-Encoding gzip;
  }

  listen 80;

}

Check and change (open the insert/edit mode in vi with “i” ) the values to your setup:

Portrait is running on port 80 on the server 192.168.1.99: proxy_pass http://192.168.1.99:80;.
Adopt this to your needs. Do not add a trailing slash “/” after the address!
As already mentioned above, web sockets are needed in order to be able to work with the web-configurator. The four lines under #proxy web sockets are enabling the sockets in the reverse proxy.
With proxy_set_header X-real-IP $remote_addr; the client IP is forwarded to Portrait.

Save the file (In vi: Escape the insert/edit mode with “ESC” and the type “:wq” to save and close the editor).

Restart nginx with systemctl restart nginx. If you made a typo in the configuration, the service will not start. Check systemctl status nginx to see a log output that explains the issue.

After nginx restarted, you successfully set up nginx as a reverse proxy. Next step is to activate TLS/SSL.

Activate TLS/SSL with certbot

Portrait without TLS is a very bad idea – not only is the communication unencrypted, features like “Install as app” or camera access is forbidden. Therefore, we need to set up TLS.

Certbot is a free, open source software tool to automatically administer Let's Encrypt TLS/SSL certificates for websites. Let's encrypt certificates are free and also available for commercial use.

Please note that you will also have to get the nginx extension for certbot. Certbot will automatically make the needed changes to your configuration files.

For the installation of certbot please refer to their website (https://certbot.eff.org/). There, you should be able to find the instructions for your host OS.
Standard setup = https://certbot.eff.org/instructions?ws=nginx&os=pip:
Follow the instructions until point 7 (Choose how you'd like to run Certbot)

After these instructions, run sudo certbot --nginx.

Now, a wizard will guide you through the setup of TLS with Let's Encrypt. Make sure to also activate the HTTP to HTTPS referrer.

Once set up, you do not need to maintain the certificates: Certbot will take care of future renewals of your certificate.

After you run the wizard, your config will file will look like this:

A restart is not needed. Next time you open portrait.customer.com in your browser, TLS is active.

To make sure everything runs, use:

Now you can also try to ping your needed server!

FAQ

I get a 502 error when trying to open portrait

This means that the reverse proxy is working, but cannot reach the Portrait server:

Make sure to check if your Portrait instance is running. Check if all containers are up: docker-compose ps
Check the nginx configuration file. It is important that you have no trailing slash behind the IP address in proxy_pass. Correct would be: proxy_pass http://192.168.1.99;
Verify the network connection between proxy and portrait server. Run this command on the proxy server to check the connectivity: curl 192.168.1.99:80 The output should be the raw HTML of the login page.

Portrait - 7.x

Set up a reverse proxy

Reference setup

Install nginx

Configuring nginx

Activate TLS/SSL with certbot

FAQ

I get a 502 error when trying to open portrait