Offline Installation (Docker)

Install Connectware on Docker in offline environments using Docker Compose.

This guide walks you through the process of installing Connectware in offline environments using Docker Compose. The offline installation process is designed for environments where Internet access is limited, unavailable, or restricted for security reasons.

The offline installation process has two phases:

1. Preparation phase: Use a donor PC with Internet access to download the Docker images, the installer script, and the license files.

2. Installation phase: Transfer the files to the recipient PC and install Connectware without Internet connectivity.

Prerequisites

Donor PC Requirements

• Internet connection

• Docker installed and running

• Terminal access (Linux, macOS, or Windows with WSL)

• Connectware license key (for authenticating with the Cybus registry)

• Access to the Cybus Portal to download license files

• USB drive or other transfer medium for moving files

Connectware does not need to be pre-installed on the donor PC. The Docker images will be pulled directly from the Cybus registry. However, if you already have Connectware installed, the existing Docker images can be reused, which will save time by skipping the pull step.

Recipient PC Requirements

• Operating System: Linux

• Docker and Docker Compose installed and running

  • For more information on installing Docker, refer to the Docker documentation. Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI which are Compose prerequisites.

• No Internet connection required

• Sufficient disk space for Docker images (typically 5-10 GB for version 2.1.2)

Phase 1: Preparing Files on the Donor PC

Follow these steps on a computer with Internet access to download and prepare all required files.

1

Create a Storage Folder

• Create a dedicated folder to store all required files for the offline installation.

mkdir connectware-offline
cd connectware-offline

2

Determine the Connectware Version

Determine which Connectware version you need to install.

If you already have Connectware running on the donor PC, you can identify the installed version:

docker images | grep registry.cybus.io/cybus

Look for the version number in the image tags (e.g., 2.0.0, 2.1.0, 2.1.2).

3

Authenticate with the Cybus Registry

1. Before downloading Docker images, authenticate with the Cybus registry using your license key.

# Log in to the Cybus registry
# You will be prompted for your license key as the password
docker login registry.cybus.io -u license

1. When prompted, enter your license key (the same one you will use for installation).

Result: You are now authenticated and can pull Docker images from the Cybus registry.

4

Download Docker Images

Download all required Docker images for your Connectware version. This involves pulling images from the registry and then saving them to tar files.

If you already have Connectware installed on the donor PC, the required images may already exist locally in your Docker daemon. If all required images for your target version are present, you can skip the docker pull commands and proceed directly to the docker image save commands below.

• To verify which images are already available locally, run the following command. If all required images for your target version are listed, you can skip the pull step.

docker images | grep registry.cybus.io/cybus

• To pull the required images, run the following commands. Make sure to replace ${VERSION} with the version you want to install.

The required images may vary between Connectware versions. The list below is for version 2.1.2 and later. For earlier versions, verify the required images by checking the installer script or consulting the release notes.

# Set your Connectware version
VERSION=${VERSION}

# Pull all required images from the registry# Skip these pull commands if images already exist locally from an existing Connectware installationdocker pull registry.cybus.io/cybus/admin-web-app:${VERSION}
docker pull registry.cybus.io/cybus/auth-server:${VERSION}
docker pull registry.cybus.io/cybus/broker:${VERSION}
docker pull registry.cybus.io/cybus/container-manager:${VERSION}
docker pull registry.cybus.io/cybus/ingress-controller:${VERSION}
docker pull registry.cybus.io/cybus/ingress:${VERSION}
docker pull registry.cybus.io/cybus/nats:${VERSION}
docker pull registry.cybus.io/cybus/postgresql:${VERSION}
docker pull registry.cybus.io/cybus/protocol-mapper:${VERSION}
docker pull registry.cybus.io/cybus/resource-status-tracking:${VERSION}
docker pull registry.cybus.io/cybus/service-manager:${VERSION}
docker pull registry.cybus.io/cybus/system-control-server:${VERSION}
docker pull registry.cybus.io/cybus/topic-explorer:${VERSION}
docker pull registry.cybus.io/cybus/workbench:${VERSION}

# Save all images to tar files
docker image save -o admin-web-app_${VERSION}.tar registry.cybus.io/cybus/admin-web-app:${VERSION}
docker image save -o auth-server_${VERSION}.tar registry.cybus.io/cybus/auth-server:${VERSION}
docker image save -o broker_${VERSION}.tar registry.cybus.io/cybus/broker:${VERSION}
docker image save -o container-manager_${VERSION}.tar registry.cybus.io/cybus/container-manager:${VERSION}
docker image save -o ingress-controller_${VERSION}.tar registry.cybus.io/cybus/ingress-controller:${VERSION}
docker image save -o ingress_${VERSION}.tar registry.cybus.io/cybus/ingress:${VERSION}
docker image save -o nats_${VERSION}.tar registry.cybus.io/cybus/nats:${VERSION}
docker image save -o postgresql_${VERSION}.tar registry.cybus.io/cybus/postgresql:${VERSION}
docker image save -o protocol-mapper_${VERSION}.tar registry.cybus.io/cybus/protocol-mapper:${VERSION}
docker image save -o resource-status-tracking_${VERSION}.tar registry.cybus.io/cybus/resource-status-tracking:${VERSION}
docker image save -o service-manager_${VERSION}.tar registry.cybus.io/cybus/service-manager:${VERSION}
docker image save -o system-control-server_${VERSION}.tar registry.cybus.io/cybus/system-control-server:${VERSION}
docker image save -o topic-explorer_${VERSION}.tar registry.cybus.io/cybus/topic-explorer:${VERSION}
docker image save -o workbench_${VERSION}.tar registry.cybus.io/cybus/workbench:${VERSION}

Example for version 2.1.2

VERSION=2.1.2

# Pull all required images
# Skip these pull commands if images already exist locally from an existing Connectware installation
docker pull registry.cybus.io/cybus/admin-web-app:${VERSION}
docker pull registry.cybus.io/cybus/auth-server:${VERSION}
docker pull registry.cybus.io/cybus/broker:${VERSION}
docker pull registry.cybus.io/cybus/container-manager:${VERSION}
docker pull registry.cybus.io/cybus/ingress-controller:${VERSION}
docker pull registry.cybus.io/cybus/ingress:${VERSION}
docker pull registry.cybus.io/cybus/nats:${VERSION}
docker pull registry.cybus.io/cybus/postgresql:${VERSION}
docker pull registry.cybus.io/cybus/protocol-mapper:${VERSION}
docker pull registry.cybus.io/cybus/resource-status-tracking:${VERSION}
docker pull registry.cybus.io/cybus/service-manager:${VERSION}
docker pull registry.cybus.io/cybus/system-control-server:${VERSION}
docker pull registry.cybus.io/cybus/topic-explorer:${VERSION}
docker pull registry.cybus.io/cybus/workbench:${VERSION}

# Save all images to tar files
docker image save -o admin-web-app_2.1.2.tar registry.cybus.io/cybus/admin-web-app:2.1.2
docker image save -o auth-server_2.1.2.tar registry.cybus.io/cybus/auth-server:2.1.2
docker image save -o broker_2.1.2.tar registry.cybus.io/cybus/broker:2.1.2
docker image save -o container-manager_2.1.2.tar registry.cybus.io/cybus/container-manager:2.1.2
docker image save -o ingress-controller_2.1.2.tar registry.cybus.io/cybus/ingress-controller:2.1.2
docker image save -o ingress_2.1.2.tar registry.cybus.io/cybus/ingress:2.1.2
docker image save -o nats_2.1.2.tar registry.cybus.io/cybus/nats:2.1.2
docker image save -o postgresql_2.1.2.tar registry.cybus.io/cybus/postgresql:2.1.2
docker image save -o protocol-mapper_2.1.2.tar registry.cybus.io/cybus/protocol-mapper:2.1.2
docker image save -o resource-status-tracking_2.1.2.tar registry.cybus.io/cybus/resource-status-tracking:2.1.2
docker image save -o service-manager_2.1.2.tar registry.cybus.io/cybus/service-manager:2.1.2
docker image save -o system-control-server_2.1.2.tar registry.cybus.io/cybus/system-control-server:2.1.2
docker image save -o topic-explorer_2.1.2.tar registry.cybus.io/cybus/topic-explorer:2.1.2
docker image save -o workbench_2.1.2.tar registry.cybus.io/cybus/workbench:2.1.2

The image download process may take several minutes depending on your Internet connection speed. Each image will be pulled from the registry and then saved to a tar file. The tar files will be several hundred megabytes each.

5

Download the Installer Script

• Download the Connectware installer script for your target version.

# Download the installer script for a specific version
wget -O ./connectware-online-installer.sh https://download.cybus.io/${VERSION}/connectware-online-installer.sh

# Make the script executable
chmod +x ./connectware-online-installer.sh

Example for version 2.1.2

wget -O ./connectware-online-installer.sh https://download.cybus.io/2.1.2/connectware-online-installer.sh
chmod +x ./connectware-online-installer.sh

If you already have Connectware installed and the installer script is available at /opt/connectware, you can copy it from there instead of downloading it.

6

Download License Files

1. Go to the Cybus Portal.

2. Sign in with your credentials.

3. Navigate to Licenses to view your available Connectware licenses.

4. Select your license and download both the license key file (.key) and license file (.lic).

5. Save both files to your storage folder (connectware-offline).

For detailed instructions on obtaining license files, see Acquiring License Keys.

7

Transfer Files to USB Drive

Copy all files from your storage folder to a USB drive or other transfer medium:

• All Docker image .tar files

• connectware-online-installer.sh script

• License key file (.key)

• License file (.lic)

Result: You have prepared all necessary files for offline installation. You can now proceed to the recipient PC.

Phase 2: Installing Connectware on the Recipient PC

Follow these steps on the offline recipient PC to install Connectware.

1

Prepare the Installation Directory

1. Copy all files from the USB drive to a folder on the recipient PC.

2. Open a terminal and navigate to the folder containing the transferred files.

cd /path/to/your/installation/folder

2

Start Docker

Ensure Docker is running on the recipient PC:

sudo systemctl start docker

3

Load Docker Images

Load each Docker image into Docker. Replace ${VERSION} with your Connectware version.

# Replace ${VERSION} with your Connectware version
VERSION=${VERSION}

# Load all images
docker image load -i admin-web-app_${VERSION}.tar
docker image load -i auth-server_${VERSION}.tar
docker image load -i broker_${VERSION}.tar
docker image load -i container-manager_${VERSION}.tar
docker image load -i ingress-controller_${VERSION}.tar
docker image load -i ingress_${VERSION}.tar
docker image load -i nats_${VERSION}.tar
docker image load -i postgresql_${VERSION}.tar
docker image load -i protocol-mapper_${VERSION}.tar
docker image load -i resource-status-tracking_${VERSION}.tar
docker image load -i service-manager_${VERSION}.tar
docker image load -i system-control-server_${VERSION}.tar
docker image load -i topic-explorer_${VERSION}.tar
docker image load -i workbench_${VERSION}.tar

Example for version 2.1.2

docker image load -i admin-web-app_2.1.2.tar
docker image load -i auth-server_2.1.2.tar
docker image load -i broker_2.1.2.tar
docker image load -i container-manager_2.1.2.tar
docker image load -i ingress-controller_2.1.2.tar
docker image load -i ingress_2.1.2.tar
docker image load -i nats_2.1.2.tar
docker image load -i postgresql_2.1.2.tar
docker image load -i protocol-mapper_2.1.2.tar
docker image load -i resource-status-tracking_2.1.2.tar
docker image load -i service-manager_2.1.2.tar
docker image load -i system-control-server_2.1.2.tar
docker image load -i topic-explorer_2.1.2.tar
docker image load -i workbench_2.1.2.tar

Result: All Docker images are now loaded and available for use.

4

Run the Installer in Offline Mode

Run the installer script in offline mode using the -o flag:

sudo ./connectware-online-installer.sh -o

The installer will prompt you for configuration options and then generate a docker-compose.yml file in the current directory.

The -o flag tells the installer to run in offline mode, which skips Internet connectivity checks and uses local Docker images. The installer is still interactive and will prompt for:

• Installation directory (default: /opt/connectware)

• Ingress hostnames

• Whether to run as a systemd service

To run a non-interactive installation, use silent mode with additional flags:

sudo ./connectware-online-installer.sh -o -s -d /opt/connectware -H localhost -k <your-license-key>

The installer validates that all required Docker images are present before proceeding. If any images are missing, the installation will fail with an error listing the missing images.

5

Configure the License

1. Open the generated docker-compose.yml file in a text editor:

nano docker-compose.yml

1. Locate the system-control-server service section and find the CYBUS_LICENSE_FILE environment variable.

2. Open your license file (.lic) and copy its entire content.

3. Paste the license content as the value for CYBUS_LICENSE_FILE:

system-control-server:
  environment:
    CYBUS_LICENSE_FILE: |
      -----BEGIN LICENSE-----
      [Your license content here]
      -----END LICENSE-----
    CYBUS_REGISTRY_PASS: ${CYBUS_REGISTRY_PASS}
    NODE_ENV: production
  hostname: system-control-server
  image: registry.cybus.io/cybus/system-control-server:2.1.2
  # ... rest of the configuration

1. Save and close the file.

Ensure you paste the entire content of the .lic file, including the -----BEGIN LICENSE----- and -----END LICENSE----- markers.

6

Start Connectware

Start Connectware using Docker Compose:

docker compose up -d

Docker Compose will create and start all Connectware containers in the background.

Result: Connectware is now running on the recipient PC.

Accessing Connectware

After installation, you can access Connectware through your web browser:

1. Open your web browser.

2. Navigate to https://localhost or the hostname you configured.

3. Log in using the default credentials:

   • Username: admin

   • Password: admin

For security reasons, change the default admin password immediately after your first login. See Default Admin User for more information.

Uploading the License File

If prompted to upload a license file in the Admin UI, follow these steps:

1. In the Admin UI, navigate to System > System Status.

2. Click the License tab.

3. Click Upload License File.

4. Select your .lic file and confirm the upload.

License Validation in Offline Environments

When running Connectware in an offline environment, you may see a warning message in the License View indicating that the system cannot connect to the license validation server at https://graphql-server.cybus.io/graphql.

This warning can be safely ignored in offline installations. The license validation has already been performed locally using the license file embedded in the docker-compose.yml configuration. Your license will show as valid.

The license information is stored locally in the docker-compose.yml file and does not require Internet connectivity to function. However, you will not be able to use the Refresh License button in the Admin UI, as this feature requires Internet access.

Troubleshooting

Docker Images Not Loading

Problem: Error messages when loading Docker images.

Solution: Verify that:

• All .tar files were transferred completely and are not corrupted.

• You have sufficient disk space on the recipient PC.

• Docker is running with the correct permissions.

License File Not Accepted

Problem: Connectware does not accept the license file.

Solution: Ensure that:

• You copied the entire content of the .lic file, including the -----BEGIN LICENSE----- and -----END LICENSE----- markers.

• The license file is valid and not expired.

• You pasted the content correctly in the docker-compose.yml file without extra spaces or line breaks.

Containers Not Starting

Problem: Some or all containers fail to start.

Solution:

• Check container logs: docker compose logs

• Verify all images loaded successfully: docker images | grep cybus

• Ensure ports 80 and 443 are not in use by other applications.

Cannot Access Connectware

Problem: Cannot access the Connectware Admin UI in the browser.

Solution:

• Verify all containers are running: docker compose ps

• Check if ports are accessible: netstat -tuln | grep -E ':(80|443)'

• Try accessing using the server's IP address instead of localhost.

Next Steps

After successfully installing Connectware in offline mode, you can:

• Connect your first machine

• Configure user management

• Install additional services