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).
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