Installing Connectware on Docker Compose

Now you know all the prerequisites you need! So we can start with the installation of Connectware. Installing Connectware is made easy using the prebuilt installer script provided by Cybus. To download and use the script follow the steps below. 

1. Download the installer script for the desired version of Connectware on your host system. This can be found at:

https://download.cybus.io/<VERSION>/connectware-online-installer.sh 

To clarify, 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
Code-Sprache: YAML (yaml)

2. This step is 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
Code-Sprache: YAML (yaml)

3. You now need to make the script executable so it can be run as a script.

$ chmod +x ./connectware-online-installer.sh
Code-Sprache: YAML (yaml)

The installer script is now ready to be executed.

First Fime Installation

1. Run installer script. We recommend executing the script as sudo in order to run Connectware as a systemd service and/or if the install directory (usually /opt/connectware) requires admin privileges.

$ sudo ./connectware-online-installer.sh
Code-Sprache: YAML (yaml)

2. In the dialog, verify that the correct Connectware version is displayed and press Enter.

3. You will now be prompted for the installation desired target directory. In this example we will press enter to go with the default path  /opt/connectware
4. The installer script will then run some preflight checks to make sure that all system requirements are met. Something went wrong? Please go back to the welcome article and recheck  the prerequisites again.

If all requirements are met then you should be able to 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!
Code-Sprache: YAML (yaml)

5. Enter your Cybus Connectware credentials. If your credentials are valid, the following output is displayed:

Verifying license key...
Login succeeded.
Code-Sprache: YAML (yaml)

6. You will now be asked whether you would like to boot Connectware as a system-service. We highly recommend this otherwise, the application must be started by hand every time the host system starts. In this example we will type “y” to confirm the decision to boot Connectware as a system-service. 

Please choose the startup behavior
-------------------------------------------
Start automatically on boot via system-service? [y/N]
Code-Sprache: YAML (yaml)

7. The installer script will then print your chosen options and ask you to confirm they are correct.

By following the previously mentioned example, you should be able to see the following output: 

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]
Connectware license key:       [VALID]
Code-Sprache: YAML (yaml)

8. The container images required for Connectware will now be pulled onto your system. After they are successfully pulled, the installer script will check for old container images from previous Connectware versions, which can safely be removed („pruned“) to clean up your disk space. The installer will ask for confirmation before any container images are removed. In this example the prompt  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]
Code-Sprache: YAML (yaml)

9. 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 and which commands you need to enter to run or stop Connectware.

If you followed our example, you will get this output in the last step: 

Successfully installed Connectware!
===================================
You can find the installation directory at /opt/connectware.
In order to stop type:
systemctl stop connectware
Code-Sprache: YAML (yaml)

Congratulations, you have successfully installed the Cybus Connectware for the first time. 

How to run 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. 

If you want to use this way of deploying Connectware, the license key has to be provided 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.

How to update from an older version? 

Updating an existing Connectware is just as easy as installing a new one. All you need to do is download the new installer script by following the same steps described above and install in the same directory where Connectware is running.

All your custom settings like license key or network settings will automatically be migrated. If you are asked for your license key during the update, you might have specified a different installation directory. If this is the case, please cancel the update and ensure you choose the correct installation path.

If you had previously installed Connectware using elevated privileges, remember to execute the new script also using sudo. 

How to update in silent mode? 

The easiest way to update to a newer version is to run the update in silent mode. All you have to do is to start the installer script using the silent -s and directory -d flags.

$ ./connectware-online-installer.sh -s -d <PATH/TO/YOUR/CONNECTWARE/FOLDER>
Code-Sprache: YAML (yaml)

How to change 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
Code-Sprache: YAML (yaml)

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>
Code-Sprache: YAML (yaml)

How to remove Connectware? 

Removing Connectware from your system is a manual process. Follow the steps below in your terminal to remove Connectware.

1. Stop the running Connectware instance. If Connectware has been installed as a systemd service, simply run the command systemctl stop connectware. Otherwise change into your installation directory and manually stop the running instance with docker-compose down. 

2. This step is optional:. Remove the systemd service. If the systemd service was deployed it has to be stopped and disabled before it can be removed:

$ systemctl stop connectware
$ systemctl disable connectware
$ rm /etc/systemd/system/connectware.service
Code-Sprache: YAML (yaml)

3. Remove the installation directory. Now that Connectware has been stopped you can remove all local files within your installation directory. 

$ rm -rf /opt/connectware
Code-Sprache: YAML (yaml)

4. Next, clean docker artifacts. The final step is to remove all remaining docker artifacts that are still on your system.

List all images, containers, volumes and networks: 

$ docker images -a
$ docker container ls -a
$ docker volume ls
$ docker network ls
Code-Sprache: YAML (yaml)

For removing a specific:

container

$ docker container rm <CONTAINER-NAME>
Code-Sprache: YAML (yaml)

image

$ docker image rm <IMAGE-NAME>
Code-Sprache: YAML (yaml)

volume

$ docker volume rm <VOLUME-NAME>
Code-Sprache: YAML (yaml)

network

$ docker network rm <NETWORK-NAME>
Code-Sprache: YAML (yaml)

If you have no docker applications other than Connectware running on your system, you can also simply remove all artifacts by running

$ docker system prune -a -f
Code-Sprache: YAML (yaml)

Please keep in mind that this will remove all currently unused docker resources, not only those created by Connectware.

Finishing Installation of Connectware

Congratulations, after following all the steps above Connectware is now installed. You can access the Admin UI by opening your browser and entering the host’s IP address directly:

https://<HOST-IP>

The initial login credentials are:

username: admin

password: admin