You need access to the server via SSH to perform the following steps. This is a guide for the customer.

This section is for the initial setup of an SSL certificate. If you want to renew your certificate, please scroll down to the second part of the instructions.

Please replace the red sections with your data.

Creating a Certificate Signing Request (CSR)

Root access is required to set up SSL. Instead of vim, a more user-friendly editor such as nano can be used.

1. generation of a private key

cd /etc/ssl/private
openssl genrsa -out fqdn.key.pem 2048

Please replace the part highlighted in red with the FQDN of your Q.wiki. For example: qwiki.acme.local

2. create the CSR

vim fqdn.csr.conf

Insert the following into this file (please change the sections marked in red with your data):

[req] distinguished_name = req_distinguished_name 
req_extensions = v3_req 
prompt = no 
[req_distinguished_name] 
C = DE
ST = NRW 
L = AACHEN 
O = Modell Aachen GmbH
OU = IT-Services
CN = QWIKI-ALIAS.ACME.LOCAL (the URL for accessing Q.wiki in the browser
)
emailAddress = technicalAP@customer.de 
[v3_req] 
keyUsage = keyEncipherment, dataEncipherment 
extendedKeyUsage = serverAuth 
subjectAltName = @alt_names 
[alt_names] 
DNS.1 = QWIKI-ALIAS.ACME.LOCAL 
DNS.2 = qwikiserver.acme.local (fqdn of the servers)

After saving, the CSR can be created with the following command:

openssl req -new -out fqdn.csr -key fqdn.key.pem -config fqdn.csr.conf
 

This command creates a fqdn.csr file in the current directory. This can be downloaded via SCP. Alternatively, the content can also be copied and pasted into an “fqdn.csr” on a Windows computer. The CSR can be used to request a new certificate in your CA.

Set up or update an SSL certificate

1. Place the certificate and possibly the key on the Q.wiki server in /etc/ssl/private. All further steps, unless otherwise stated, will be carried out in this directory.

2. Check format. 

You will need an RSA key (without a password – if there is a password, you can see it in step 3), as well as a base64-encoded X509 certificate. DER and PKCS#12 must be converted.

DER konvert

openssl x509 -inform der -in fqdn.xyz -out fqdn.cert.pem 

PKCS#12 konvertieren 

extract private key

openssl pkcs12 -in fqdn.pfx -nocerts -nodes -out fqdn.key.pem 

Extract certificate

openssl pkcs12 -in fqdn.pfx -clcerts -nokeys -out fqdn.cert.pem

3. Check private key

openssl rsa -noout -in fqdn.key.pem

If a password prompt appears, it must be removed, otherwise the password will have to be entered manually each time the web server is restarted. 

4. Customize file permissions

chown root:root fqdn.* 
chmod 0600 fqdn.*

If you have only updated the certificate, you can jump to point 7.

5. edit the nginx configuration. (only necessary for the initial setup of SSL, or if the file names of the certificate have been changed) 

vim /etc/nginx/sites-enabled/qwiki_http.conf

The existing configuration must be deleted and replaced with the following customized configuration.

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name qwiki_http;
    rewrite ^/(.*)$ https://qwiki.acme.local/$1 permanent;
}

server {
    listen 443 default_server ssl;
    listen [::]:443 default_server ssl;

    server_name qwiki_https;

    root /var/www/qwikis/core;

    ssl_certificate /etc/ssl/private/CERT;
    ssl_certificate_key /etc/ssl/private/KEY;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location ~ (/pub/System|/robots.txt) {
    sendfile on;
    tcp_nopush on;
    expires 7d;
    add_header Cache-Control "public, no-transform";
}

location /api/phoenix {
        proxy_http_version 1.1;
        proxy_set_header  Host $host;
        proxy_set_header  Upgrade $http_upgrade;
        proxy_set_header  Connection "upgrade";
        proxy_set_header  X-Real-IP $remote_addr;
        proxy_set_header  X-Scheme $scheme;
        proxy_set_header  X-Forwarded-Proto $scheme;
        proxy_set_header  X-Forwarded-Host $host;
        proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass        http://elixir;
    }

location / {
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Scheme $scheme;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_pass http://qwiki;
}
}

6. Customizing the Q.wiki configuration file (only necessary for initial SSL setup)

vim /var/www/qwiki/core/lib/LocalSite.cfg

Search this file for the Q.wiki host entry “DefaultUrlHost” and jump to the result with the fqdn of your system. 

Here, the 'http' must be replaced by a 'https' / extended. 

Then save the file and restart the services (point 7).

7. Restart the services

a2enmod ssl
systemctl restart nginx qwiki

Updating an SSL certificate from version 6.8

1. Open the Q.wiki command shell

qmmander

2. Open Q.wiki configuration

3. adjust the certificate and key paths to the new one or overwrite old certificates - we usually store the certificate and key under /root/qwiki/

ABSOLUTE_TLS_CRT_PATH: [/path/to/your/cert]
ABSOLUTE_TLS_KEY_PATH: [/path/to/your/key]

4. Update Q.wiki configuration

qmmander
10) Update certificate