Adding SSL to Localhost

This guide assumes you already followed the instructions for setting up a 4ALLPORTAL (opens new window) and your installation is running at http://localhost:8181/.
After following this guide, you can access the local 4ALLPORTAL at https://localhost:8443, which is, for example, important when using our 4Apps PowerPoint Plugin and InDesign Plugin. Without HTTPS, they would not launch properly.

1. Install mkcert

mkcert is a simple tool for creating locally-trusted development certificates. To install, please follow the instruction on their GitHub.

https://github.com/FiloSottile/mkcert#installation (opens new window)

After a successful installation, run the following command to create and install a new local Certificate Authority (CA):

mkcert -install

Please note: This command only installs the CA to the computer's local trust stores, so its browsers will not complain about invalid/self-signed certificates for certificates created with mkcert. We will create the actual certificate in the next step.

2. Create a Certificate for your Installation

To create a new certificate, change the working directory to the directory that contains the docker-compose.yml:

cd /4allportal
# ls should print the docker-compose.yml
ls

# Create a new directory for your certificates and keys
mkdir certs
cd certs

# Create the certificate and key using mkcert
mkcert localhost 127.0.0.1 ::1

This command should have created two new files in the certs directory:

• localhost+2-key.pem
• localhost+2.pem

3. Configure the Nginx Service

The 4ALLPORTAL container cannot directly consume HTTPS traffic. To handle it, a new service web needs to be created.
In this guide we use Nginx, a commonly used reverse proxy. Others like Traefik would also work.

1. Add the following snippet to the end of your docker-compose.yml file.

  web:
    image: nginx
    ports:
      - "8080:8080"
      - "8443:8443"
    volumes:
      - "./certs:/etc/nginx/certs"
      - "./nginx.conf:/etc/nginx/nginx.conf"

Note that web is left padded with two spaces. Indentation is important in yaml.

2. Add a new file nginx.conf to the /4allportal folder with the following content:

worker_processes 1;

events { worker_connections 1024; }

http {

    upstream up4ap {
        server 4allportal:8181;
    }

    server {
      listen 8443 ssl http2;
      server_name localhost;

      ssl_certificate /etc/nginx/certs/localhost+2.pem;
      ssl_certificate_key /etc/nginx/certs/localhost+2-key.pem;
  
      ssl_session_cache   shared:SSL:10m;
      ssl_session_timeout 10m;
      ssl_protocols       TLSv1.3;
      ssl_ciphers         HIGH:!aNULL:!MD5;
      
      sendfile on;
      client_max_body_size 100M;

      location /service/comet/ {
        proxy_pass         http://up4ap;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        
        proxy_set_header   Host $server_name;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_set_header   X-Forwarded-Host $server_name;
      }

      location / {
        proxy_pass         http://up4ap;
        proxy_redirect     off;
        proxy_set_header   Host $server_name;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_set_header   X-Forwarded-Host $server_name;
      }
   }
}

3. up all your services that lie in the same folder as the docker-compose.yml with the following command:

docker compose up -d

After some moments, everything should be up and running.

4. Check your Browser

Try accessing https://localhost:8443/ (opens new window). If everything worked well, browsers on the same machine should not complain, meaning that your certificate is considered valid.