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

Optional: if you are unsure, which pathes on your host are currently used by your setup, you can use the following commands to show all used mounts of the currently running containers:

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 (6.5/7.0 to 8.0 only)

If you are upgrading to 8.0 from 7.1, you can skip this step.

Simplifier 7.1 introduced changes for KeyValue Store and JSON Store plugins. Starting with 7.1, these plugins 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 and your security.toml file

cp .env ../env_old
cp security.toml ../security.toml_old

Revert changes:

git restore security.toml
git restore .env

This may result in a error message “error: pathspec ‘.env’ did not match any file(s) known to git”. This is not a problem, it depends how old your copy of the repository is. If you get this error, you are already using a newer version.

Now you should not have any changed files which are under version control. To verify this, enter

git status

The output should look similar to, but nothing more:

On branch release/7.0
Your branch is up to date with 'origin/release/7.0'.

nothing to commit, working tree clean

especially there should be no part in the ouput like:

Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)

If you see this in your output, you still have changed files, which will be listed after this message. Please make a copy and restore these files like described for security.toml and .env. If you are an experienced git user, you can also stash your changes and apply them after pulling.

Update the content and switch to the new release branch:

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

Check the new content

ls -a

You should see at least the following entries:

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

.env.template is 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.template 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. There is no security.toml anymore. Copy the template, this will make future updates easier.

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

• mysql: database backend for Simplifier
• traefik: reverse proxy server
• simplifier: application server
• launchpad: Simplifier Launchpad (new in 7.1)
• workflow-runtime: Runtime module for the workflow engine (new in 8.0)
• workflow-designtime: Designtime module for the workflow engine (new in 8.0)
• watchtower: automated updates
• mysqlinit: initial database configuration (new in 7.1/8.0)

In most cases, you can leave this file unchanged.

Step 7 – Prepare the environment

With Release 8, there are a lot of new variables. It is easier always using the new template and just adopting the values, instead of adding the new variables to the old .env file.

Following the previous steps, now you have a copy of your env file als env_old in the parent directory, the current directory has no .env file. Please verify this.

After verification, make a copy of our new .env.template:

cp .env.template .env

Edit the new .env file, make sure you can read your env_old, e.g. in another terminal window.

At least the first three variables need to be changed:

# these 3 variables need to be changed
SIMPLIFIER_HOSTNAME=example.simplifier.cloud
DB_PASSWORD=MySecret123
DB_ROOT_PASSWORD=MySuperSecret

These variables need to have the same value as your previous installation.

In case you are upgrading from 6.5 or 7.0:

With 7.1, one new variable was added: HOST_DATA_PATH. It defines the root path for all permanent storage. In a default setup, this is /var/lib/simplifier. If you used a different path, either move your data to /var/lib/simplifier to follow our recommendation, or adjust this variable to point to your root directory, where all other simplifier data directories are stored.

Caution: in the following prompts, /var/lib/simplifier is used. Please always exchange this with your root location (the value of HOST_DATA_PATH) when using a different path.

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:

mkdir -p /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/

In case you are upgrading from 7.1:

Make sure that HOST_DATA_PATH has the same value as in your previous setup.

Caution: in the following prompts, /var/lib/simplifier is used. Please always exchange this with your root location (the value of HOST_DATA_PATH) when using a different path.

Now you can save and close the .env file.

If you upgraded from 6.5/7.0 to 7.1, and now to 8.0, we expect that you followed the guide and moved your traefik configuration to /var/lib/simplifier/traefik (or ${HOST_DATA_PATH}/traefik, to be precise). If not, you should really change that now. See the previews paragraph with upgrade instructions from 6.5/7.0.

For all upgrade paths:

mkdir -p /var/lib/simplifier/workflowRuntime
mkdir -p /var/lib/simplifier/workflowDesigntime
chown 1000:1000 /var/lib/simplifier/workflowDesigntime

Optional: a list of all env variables with a short description:

Step 8 – JVM Parameter

This step is only necessary, if you used a jvm.arg file to customize the JVM parameters, e.g. to extend the memory Simplifier is allowed to consume.

With the current setup, the content of the jvm.arg file is ignored. You can customize the allowed memory. For that, change the value of SIMPLIFIER_JVM_HEAP_GB in your .env file. The number refers to the amount of memory in Gigabyte Simplifier App Server is allowed to use. This refers to the -Xmx parameter in the jvm.arg file. Set this variable to the value you defined in your jvm.arg file. To avoid irritations, we recommend to delete jvm.arg, since it is not used.

If any of the other value in the jvm.arg file differs from the recommendation you got from Customer Success, please contact Customer Success or raise a ticket in our support portal to clarify your setup.

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

There were no changes in the setup of TLS with the 7.1 or the 8.0 release. If you already have a setup based on our provided docker compose template, no changes are needed. If you are migrating from another installation type, please follow the steps 5 and 6 as described here in our installation guide.

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 your known credentials or external login provider.

Step 11 – Update Standard Content

Download the current standard content here and import it (Documentation). Remember to enable the Overwrite switch.

 FREE

Standard Content 8.0

This package contains the Standard Content 8.0 for Simplifier. It contains the Explored Application, Widgets, Widget Groups, Connectors, App Wizards and other ...

Step 12

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

rm /var/lib/simplifier/env_old