Portrait relies on authentication based on email-addresses. Therefore, Portrait requires an SMTP connection to be able to send invites, verify-links and password-resets per E-Mail.

You can either use your internal SMTP server or a dedicated and paid service provider.

SMTP providers known to us:

• Amazon SES

• Mailgun

• Sendgrid

• Sendinblue

• SMTP.com

Since external SMTP providers are optimized for transactional mailing, the changes are more likely, that your email invites or password-resets are not considered as spam.

Settings

Changing the SMTP configuration requires a backend restart.

In case of an error, please check the backend logs for further analysis.

Configuration Examples

These examples help you to set up your SMTP connections.

Sendinblue

After you have set up your Sendinblue account, you can use the following configuration.

Look up the “SMTP key” inside your account settings of sendinblue and use this as password in the configuration of portrait:

spring:
  mail:
    host: smtp-relay.sendinblue.com
    port: 587
    username: no-reply@customer.com
    password: 'your-secret-smtp-key'
    tls: true
    properties.mail.smtp:
      from: 
      auth: true
      starttls.enable: true

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.

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

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)

# We need the plugin for nginx and certbot
sudo apt install certbot python3-certbot-nginx

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.

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

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 [::]:443 ssl; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/portrait.customer.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/portrait.customer.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = portrait.customer.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


  listen 80;
  listen [::]:80;

  server_name portrait.customer.com;
    return 404; # managed by Certbot
}

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

To make sure everything runs, use:

sudo systemctl restart nginx
sudo systemctl status nginx

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.

It is possible to set up Portrait with public access. This allows users to access your data in Portrait without having a user.

In the following, we will explain the steps you need to take to make your instance publicly accessible. For public access, we strongly recommend running Portrait through a reverse proxy, please refer to Set up a reverse proxy for further information in this matter.

Enabling public access

Public access is enabled in the .env file. The .env file is located under <Portrait Installation Path>/app/config/frontend. For further information about the .env file, please refer to Advanced UI Settings.

In the .env file, set NEXT_PUBLIC_PUBLIC_ACCESS to true. After a restart of Portrait, you should be able to access your Portrait instance without having to log in now.

Accessing the administration site with public access enabled

As an administrator in order to access the administration panel while in public mode, type in https://<portrait.customer.xyz>/admin

From there, you can log in and administer your instance.