Installing Connectware on Docker

Prerequisites

• You have a license key.

• You have a Internet connection to download Docker images from registry.cybus.io.

• Docker and Docker Compose are installed and running on your host.

  • For more information on installing Docker, refer to the Docker documentation. Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI which are Compose prerequisites.

• You are familiar with Docker. For more information on using Docker, see our Docker Basics Lesson.

Preparing the Installer Script

The installer script allows you to quickly install Connectware.

1. Download the installer script for the Connectware version that you want to install.

   • Download link for the installer script of the latest Connectware version: https://download.cybus.io/latest/connectware-online-installer.sh

   • To download the installer script for a specific Connectware version, use the following link and replace <VERSION> with the Connectware version: https://download.cybus.io/<VERSION>/connectware-online-installer.sh

   • For example, to download the installer script for Connectware 1.7.1, use the following link: https://download.cybus.io/1.7.1/connectware-online-installer.sh In the example below, we will use the latest version of Connectware.

$ wget -O ./connectware-online-installer.sh https://download.cybus.io/latest/connectware-online-installer.sh

1. Optional: It is a security risk to run bash scripts downloaded directly from the web. So feel free to open the installer script and check its contents.

$ cat connectware-online-installer.sh

1. Make the script executable so it can be run as a script.

$ chmod +x ./connectware-online-installer.sh

You can now run the installer script to install Connectware.

Running the Installer Script

The installer script does not need admin (sudo) privileges to run, except if you want to set up Connectware as a systemd service (recommended) or if the installation directory requires extra permissions. In this example, we will install Connectware as a systemd service, so we will use sudo.

1. Run the installer script.

$ sudo ./connectware-online-installer.sh

1. The version of Connectware will be printed with a greeting. To confirm that the version is correct, press enter.

2. You will now be asked for your desired target directory for installation. In this example we will press enter to go with the default path: /opt/connectware

3. The installer script will then run preflight checks to make sure that all system requirements are met. If they are not then please check the prerequisites section at the beginning of this lesson.

If all requirements are met then you should see the following output.

Running preflight checks.
=========================
Validating write permission to installation location /opt/connectware: [OK]
Checking whether this system has systemd: [YES]
Validating required utility installation: [OK]
Validating Cybus docker-registry connection: [OK]
Validating Docker installation: [OK]
Validating Docker Compose installation: [OK]
Validating that no former Connectware is running: [OK]
Preflight checks finished successfully!

1. You will now be prompted for your Cybus license key. If your credentials are valid then you should see the following output.

Verifying license key...
Login succeeded.

1. You will now be asked whether you would like to boot Connectware as a system-service. Without this, the application must be started by hand every time the host system starts. In this example we will press enter to confirm yes.

2. The installer script will then print your chosen options and ask for confirmation that they are correct. If you followed this example then you should see the following.

Please review and confirm the following Connectware configuration:
------------------------------------------------------------------

Connectware license key:       [VALID]
Installation directory:       /opt/connectware
Autostart as systemd service: true

Accept configuration? [Y/n]

1. The Connectware container images will then pulled onto your system. After they are successfully pulled, the installer script will check for old container images of previous Connectware versions, which can safely be removed („pruned“) to clean up disk space. The installer will ask for confirmation before any container images are removed. In this example the question looks as follows.

-----------------------------------------
Removing old Docker images
-----------------------------------------

The following Docker images are from previous Connectware versions and can be removed:

REPOSITORY                            TAG          IMAGE ID  CREATED      SIZE
registry.cybus.io/cybus/admin-web-app ***********  e561383a5 24 hours ago 21.5MB
REPOSITORY                            TAG          IMAGE ID  CREATED      SIZE
registry.cybus.io/cybus/auth-server   ***********  a65b7f32f 24 hours ago 165MB
REPOSITORY                            TAG          IMAGE ID  CREATED      SIZE
registry.cybus.io/cybus/broker        ***********  80dd0fb24 24 hours ago 56.7MB
(...)

-----------------------------------------

Should the above docker images be removed from your local computer (pruned)? [Y/n]

1. After confirming your choice, you can observe the result of the image removal operation. As the last step, the installer will print a message telling you Connectware has been started or which commands you need to enter to run or stop Connectware. In our example you should be prompted with the following.

Successfully installed Connectware!
===================================
You can find the installation directory at /opt/connectware.
In order to stop type:
systemctl stop connectware

Running the Installation in Silent Mode

Running the installer with the -s or --silent flag will start the installation in an automated mode without the need of user interaction.

To use this way of deploying Connectware the license key has to be supplied using the --license-key flag.

This deploys Connectware in a minimal configuration to the default /opt/connectware directory without installing the systemd service.

You can further personalize your installation using the supported installation flags. To see a full list of options just run the installation script with the --help flag.

Changing SSL Certificates

In case you need to update or change the certificate files (for example if you renewed them using certbot with Let’s Encrypt or want to add a self-signed certificate) you can do this by copying them to Connectware:

$ docker cp -L <path-to/your-key-file.key> <your-connectware-container>:/connectware_certs/cybus_server.key
$ docker cp -L <path-to/your-cert-file.crt> <your-connectware-container>:/connectware_certs/cybus_server.crt

The name of your Connectware container depends on the directory it was installed to and is rendered as <your-connectware-directory>_connectware_1. By default Connectware is installed to /opt/connectware/ which results in the container name connectware_connectware_1.

Restart the Connectware proxy to apply the changed files.

$ docker restart <your-connectware-container>