Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages
Cybus Learn |

Installing the Connectware (Self-Hosted)

How to | 17 September 2020

Installing the Connectware (Self-Hosted)

By: Marius Schmeding |

Introduction

In this lesson you will learn how to install the Connectware directly onto your Linux or Mac host system. The following topics are covered by this article:

  • Acquiring a license
  • Installing the Connectware
  • Updating the Connectware
  • Changing SSL certificates
  • Removing the Connectware

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 menu bar.

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.

selfhosted appliance

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

create new instance at cybus portal

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.

create self-hosted instance

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

generate license key

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


IMPORTANT

Upgrading from any prior 0.x.x version to 1.0.0 (or later) will break your running installation. We recommend to thoroughly read through the changes introduced in 1.0.0 as well as the upgrading information before attempting any updates. When in doubt, please consider contacting our support team.


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 1.0.20

$ wget -O ./connectware-online-installer.sh https://download.cybus.io/1.0.20/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) 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

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

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

6) You will now be asked whether 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

Accept configuration? [Y/n]

8) 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]

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 the Connectware has been started or which commands you need to enter to run or stop 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>

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

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, check out our docs at https://docs.cybus.io/ or see more guides here.

Check out our media to this article: