Installing the Connectware (Self Hosted)

Marius Schmeding 2019-05-13

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 Docker Registry and that you are authorized to pull Connectware images. If you have no valid credentials, please contact our sales team.

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.

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/connectware-online-installer-<VERSION>.sh In the example below we will use 0.33.1

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

The output is expected to look similar to this:

--2019-05-13 15:09:03--  https://download.cybus.io/connectware-online-installer-0.33.1.sh
Resolving download.cybus.io (download.cybus.io)... 99.84.92.13, 99.84.92.52, 99.84.92.39, ...
Connecting to download.cybus.io (download.cybus.io)|99.84.92.13|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 15110 (15K) [application/x-sh]
Saving to: ‘connectware-online-installer-0.33.1.sh’

connectware-online-installer-0.33.1.sh               100%[=====================================================================================================================>]  14.76K  --.-KB/s    in 0s

2019-05-13 15:09:03 (121 MB/s) - ‘connectware-online-installer-0.33.1.sh’ saved [15110/15110]

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

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

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

The installer script is now ready to be ran.

Run Installer Script

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

Upgrading from previous versions requires to run the script with the --remove parameter in order for the .env file to be recreated.

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 Registry credentials. If you have no valid credentials, please contact our sales team.

If your credentials are valid then you should see the following output.

Verifying user credentials...
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 user:             <YOUR USERNAME>
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

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 going to https://localhost.

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.