In this lesson you will learn how to install the Connectware directly onto your Linux or Mac host system.
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 from
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.
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.
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.
4.) Create a new appliance by clicking the Create Selfhosted Instance button in the upper right corner.
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.
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.
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.
Installing the 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 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.38.2
$ wget -O ./connectware-online-installer.sh https://download.cybus.io/0.38.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.
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
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 installer with the
--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
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
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
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
$ ./connectware-online-installer.sh -s -d <PATH/TO/YOUR/CONNECTWARE/FOLDER>
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
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.
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
The initial login credentials are
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.