Installing the Connectware (Self Hosted)

Marius Schmeding 2019-11-12

Introduction

In this lesson you will learn how to install the Connectware directly onto your Linux or Mac host system.

Prerequisites

This lesson assumes that you already have an account for the Cybus Portal and that you are authorized to pull Connectware images. If you have no valid credentials, please contact our sales team.

If you want to refresh your knowledge of Docker before starting this lesson see Docker Basics Lesson.

Docker and Docker Compose must also be installed and running on your host. During the installation an internet connection is required to download Docker images fromregistry.cybus.io.

If Docker is not installed, start here:

If Docker Compose is not installed, then see here https://docs.docker.com/compose/install/

Mac users need to enable disk access (File Sharing / Shared Drive) in their Docker preferences.

Acquire your license key

1.) During the installation you will be asked to enter your Connectware license key. To obtain your key you have to login to the Cybus Portal using your user credentials. If you have no valid credentials please contact our sales team. Cybus Portal login

2.) Next you have to go to the Selfhosted Appliances view by selecting the appropriate entry on the left side of the menubar.

3.) This view contains all your currently deployed selfhosted Connectware appliances. If you have no selfhosted appliances deployed at the moment this view should be empty. View of the selfhosted appliances

4.) Create a new appliance by clicking the Create Selfhosted Instance button in the upper right corner. Create a new instance

5.) This opens up a new window titled Create Selfhosted Instance. Here you can enter a name to associate with the appliance you are going to create as well as select a Connectware License from the license pool associated with your account. If you have no unused licenses left please contact our sales team. Finish the appliance creation by clicking create. Instance creation window

6.) The Selfhosted Appliances view now contains a new entry with the name and license associated in step 5. To continue select the newly created appliance which will open up the license detail view.

7.) Select the Download button located in the upper right corner. Download the license key

8.) You can now generate a license key for the selected appliance by clicking on Generate License Key. The generated license key will be displayed and can be copied to the clipboard for later use. Please make sure to keep the license key as it cannot be viewed after closing the window. If the key is lost you have to repeat this step to create a new license key for the selected appliance, which invalidates any old and, under circumstances, already deployed license key. You are now prepared for the installation. License key generation view

Installing the Connectware

Installing the Connectware is made easy using the prebuilt installer script provided by Cybus. To download and use the script follow the steps below.

Prepare Installer Script

1.) Download the installer script for the desired version of the Connectware on your host system. This can be found at download.cybus.io/<VERSION>/connectware-online-installer.sh In the example below we will use 0.37.2

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

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

3.) We now need to make the script executable so it can be ran as a script.

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

The installer script is now ready to be ran.

First time installation

1.) Run installer script. Please note the installer script does not need sudo privileges to run unless you want to run the Connectware as a systemd service (recommended) or install directory requires additional permissions. In this example we will be installing the Connectware as a systemd service so we will run it with sudo.

$ sudo ./connectware-online-installer.sh

2.) The version of the Connectware will be printed with a greeting Please confirm that the version is correct and press enter.

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 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!

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

5.) 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 of opt/connectware

6.) You will now be asked if you would like to boot the 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.

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

8.) The Connectware containers will then pulled onto your system. After they are successfully pulled the installer script will print a message telling you the Connectware has been started or where to go to run the 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 the Connectware the license key has to be supplied using the --license-key flag.

This deploys the 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.

Updating from an older version

To perform an update of an existing Connectware installation is just as easy as installing a new one.

All you need to do is to obtain the new installer script by following the same steps as described in the chapters Prepare Installer Script.

To upgrade an existing installation just choose the same folder your Connectware is currently running in.

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 wrong installation directory. If this is the case, please cancel the update and ensure you choose the correct installation path.

Remember that if your existing Connectware used elevated privileges during installation to also run the update using sudo.

Updating 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>

Removing the Connectware

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

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

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

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

$ rm -rf /opt/connectware

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

To remove a specific container:

$ docker container rm <CONTAINER-NAME>

To remove a specific image:

$ docker image rm <IMAGE-NAME>

To remove a specific volume:

$ docker volume rm <VOLUME-NAME>

To remove a specific network:

$ docker network rm <NETWORK-NAME>

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

$ docker system prune -a -f

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

Using the Connectware

After following all the steps above the Connectware is now installed. You can access the Admin UI by opening your browser and entering the host's IP address directly: https://.

The initial login credentials are

username: admin

password admin

If you would like to learn more how to use the Connectware, checkout our docs at https://docs.cybus.io/ or see more guides here.