Prerequisites

You need a running Linux Server with Docker installed (Sizing). To install Docker, please follow the official documentation for your distribution, e. g.:

• • Ubuntu: https://docs.docker.com/engine/install/ubuntu/
  • Red Hat Enterprise Linux: https://docs.docker.com/engine/install/rhel/
  • Docker Compose Plugin is installed
  • Docker Version at least 20.10.17
  • Valid TLS Certificate (including Chain) for HTTPS

Step 1 – Install docker compose plugin

If you cannot execute the following command

docker compose

your Installation is too old or the compose plugin is missing. The official documentation to install docker including compose plugin is https://docs.docker.com/engine/install/

You can also check your distribution-specific repositories. For ubuntu, docker compose is part of the docker repository, which is, in most cases, enabled by default. You can install it with:

sudo apt install docker-compose-plugin

If your distribution doesn’t provide a package, you can download the docker engine via script.

Step 2 – Check the Server Sizing

In every major releaes, we will add additional amazing features, but these requires also to adjust the resource sizing of the simplifier host system. Before you plan the upgrade, please inform you about the sizing parameters.

Step 3 – Prepare your host system

Find out the relevant Docker Volumes on your simplifier host system:

for contId in `docker ps -q`; do echo "Container Name: "   `docker ps -f "id=$contId" | awk '{print $NF}' | grep -v NAMES`; echo "Container Volume: " `docker inspect -f '{{.Config.Volumes}}' $contId`; docker inspect -f '{{ json .Mounts }}' $contId  | jq '.[]';   printf "\n"; done

Remember the volume path to adjust it before you upgrade to major version.

Step 4 – Update database

Simplifier 7.1 includes changes for KeyValue Store and JSON Store plugins. With 7.1, they use a relational database as backend. By default, the main Simplifier database server is used for the plugins. If you want to use a different database backend, please refer to the detailed plugin upgrade documentation here. For this general upgrade guide, the default setup is explained.

First, make a backup of the existing file based backend files. They are named and located here:

${SIMPLIFIER_DATA_DIR}/plugins/jsonStore/jsonStore 
${SIMPLIFIER_DATA_DIR}/plugins/keyValueStore/kvstore

You need to run some SQL commands as root user. If you have a MySQL client installed, you can use it. If not, connect to the running MySQL docker container and use their mysql client:

docker exec -it mysql /bin/sh

Inside the container:

mysql -u root -p

Enter the root password for MySQL (you find it in your .env file)

It is necessary to create 2 new databases and grant the default user the necessary rights. The default user is named simplifier.

Run the following commands:

CREATE DATABASE simplifier_keyvalue;
CREATE DATABASE simplifier_jsonstore;
GRANT ALL PRIVILEGES ON `simplifier_keyvalue`.* TO `simplifier`@`%`;
GRANT ALL PRIVILEGES ON `simplifier_jsonstore`.* TO `simplifier`@`%`;
FLUSH PRIVILEGES;

Exit the MySQL client

\q

Exit the docker container:

exit

Step 5 –  Shutdown Simplifier Instance

Go to the directory where you placed the docker-compose file. Switch into that folder:

cd docker-compose

To stop Simplifier, run

docker compose -f simplifier-standalone.yml down

Step 6 – Get Simplifier setup files

Go to the directory, where you cloned the docker-compose repository. If this is not /var/lib/simplifier/bin, you should move it there:

mkdir -p /var/lib/simplifier/bin
mv docker-compose /var/lib/simplifier/bin/

Now change to that directory

cd /var/lib/simplifier/bin/docker-compose

Prerequisite: simplifier-standalone.yml is not changed, only .env file has manual entries. If this is not the case, also make a backup of simplifier-standalone.yml in the same way.

Make a backup of your .env file

cp .env ../env_old

Revert changes:

git restore .env

Update the content and switch to the new release branch:

git pull
git checkout --track origin/release/7.1

Check the new content

ls -a

You should see at least the following entries:

• .env.template
• security.toml
• simplifier-standalone.yml

.env.emplate a template file that defines the environment in terms of variable values. This files needs to be copied as .env and changed. There is no .env in the repository anymore. This will make future updates easier.

security.toml defines security settings, especially TLS certificates. It is optional, but in most cases you want to use it. This has imporoved security settings compared to the old version.

simplifier-standalone.yml is the docker-compose file, which defines the necessary services. It defines the following 5 services:

• mysql: database backend for Simplifier
• traefik: proxy server
• simplifier: application server
• launchpad: Simplifier Launchpad (new in 7.1)
• watchtower: automated updates

In most cases, you can leave this file unchanged.

Step 7 – Prepare the environment

Copy the environment template and edit the environment file

nano .env

It defines 6 variables

SIMPLIFIER_HOSTNAME=example.simplifier.cloud
DB_PASSWORD=MySecret123
DB_NAME=simplifier
DB_ROOT_PASSWORD=MySuperSecret
SIMPLIFIER_VERSION=7.1
HOST_DATA_PATH=/var/lib/simplifier

There is one new variable: HOST_DATA_PATH. It defines the root path for all permanent storage. In a default setup, this is /var/lib/simplifier. This directory is your main backup source.

Change the values of HOST_NAME, DB_NAME, DB_PASSWORD, DB_ROOT_PASSWORD to the values of your old .env file.

Now you can save and close the .env file.

The new Simplier Lanchpad needs a storage location. Create a new subfolder in /var/lib/simplifier and set matching owner and group:

mkdir -p /var/lib/simplifier/launchpad
chown 1000:1000 /var/lib/simplifier/launchpad

To simplify setup and backup, the path to store TLS certificates and Reverse Proxy (traefik) configuration was changed and is now also placed under /var/lib/simplifier. Create a new directory and move your existing files there:

mkdir -p /var/lib/simplifier/traefik
mv /etc/simplifier/traefik/* /var/lib/simplifier/traefik/

Save old security.toml file:

cd /var/lib/simplifier/traefik
mv security.toml ../security.toml.old

Step 8 – Setting up TLS (commonly referred to as SSL)

The given docker compose file configures the traefik proxy to use HTTPS only. Without further changes, a self signed default certificate will be used, which causes warnings in all major browsers. To avoid this, you need to provide your own certificates. You need the private key as well as the public key. Usually they come in form of a pair of .crt and .key files.

Edit the security.toml file.

nano security.toml

The first two sections handle the certificates and the certificates store:

[[tls.certificates]]
  certFile = "/configuration/my.custom.hostname.crt"
  keyFile = "/configuration/my.custom.hostname.key"

[tls.stores]
  [tls.stores.default]
    [tls.stores.default.defaultCertificate]
      certFile = "/configuration/my.custom.hostname.crt"
      keyFile = "/configuration/my.custom.hostname.key"

Replace “my.custom.hostname.crt” and “my.custom.hostname.key” with file names of your cert and key files.

IMPORTANT: keep the path /configuration/ unchanged. This is the path within the container, not on the host system. It is defined in the traefik service definition of the docker compose file in the section volumes.

Place all three files in /var/lib//simplifier/traefik.

cp myKeyFile.key myCertFile.crt /var/lib/simplifier/traefik
cp security.toml /var/lib/simplifier/traefik

Step 9 – OPTIONAL Configure Cipher Suites and TLS versions

Cyper security is a changing field. Algorithms which were thought to be secure may get compromised. Sometimes support for older software clients has a higher priority then state of the art security settings. This is why usually older algorithms and protocolls are supported, but can be disabled via configuration.

The prepared example file disables some older protocols and algorithms. It does only allow those, which were considered as secure at the time this article was written. This configuration is done with this part of the security.toml file:

[tls.options]
  # Valid constants: https://pkg.go.dev/crypto/tls#pkg-constants
  [tls.options.default]
    minVersion = "VersionTLS12"
     cipherSuites = [
      "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
      "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
      "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
      "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
      "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
      "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    ]
  [tls.options.mintls12]
    minVersion = "VersionTLS12"

If you have trouble in connecting with older browsers (which you shouldn’t use) or other (propriatary) clients, try to remove this part of the configuration. Instead of deleting these lines, you can place a # at the beginning of each line to mark it as a comment.

Step 10 – Starting Simplifier

So far everything is prepared and Simplifier can be started.

Change back to the folder where you stored the simplifer-standalone.yml file. To start all services which are defined in the file run:

docker compose -f simplifier-standalone.yml up -d

Now, from your desktop computer, open a new browser tab and navigate to the server. You should see a simple website which asks you to insert a Simplifer license. Copy the whole content of the licence file you received from the Simplifier Customer Success Team and paste it into the web form. Press Save. The browser now redirects you to the Simplifier login page. Log in with the default credentials admin/admin.

Step 11 – Update Standard Content

Download the current standard content here and import it (Documentation).

 FREE

Standard Content 7.1

Step 12

When you verified that everything is working as expected, remove your backup files

/var/lib/simplifier/env_old

/var/lib/simplifier/secuity.toml.old