# Offline Installation (Docker)

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](https://portal.cybus.io/) to download license files
* USB drive or other transfer medium for moving files

{% hint style="info" %}
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.
{% endhint %}

### Recipient PC Requirements

* Operating System: Linux
* Docker and Docker Compose installed and running
  * For more information on installing Docker, refer to the [Docker documentation](https://docs.docker.com/get-docker/). 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.

{% stepper %}
{% step %}

#### Create a Storage Folder

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

{% code lineNumbers="true" %}

```bash
mkdir connectware-offline
cd connectware-offline
```

{% endcode %}
{% endstep %}

{% step %}

#### 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:

{% code lineNumbers="true" %}

```bash
docker images | grep registry.cybus.io/cybus
```

{% endcode %}

Look for the version number in the image tags (e.g., `2.0.0`, `2.1.0`, `2.1.2`).
{% endstep %}

{% step %}

#### Authenticate with the Cybus Registry

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

{% code lineNumbers="true" %}

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

{% endcode %}

2. 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.
{% endstep %}

{% step %}

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

{% hint style="warning" %}
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.
{% endhint %}

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

{% code lineNumbers="true" %}

```bash
docker images | grep registry.cybus.io/cybus
```

{% endcode %}

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

{% hint style="warning" %}
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.
{% endhint %}

{% code lineNumbers="true" %}

```bash
# 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}
```

{% endcode %}

**Example for version 2.1.2**

{% code lineNumbers="true" %}

```bash
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
```

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

#### Download the Installer Script

* Download the Connectware installer script for your target version.

{% code lineNumbers="true" %}

```bash
# 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
```

{% endcode %}

**Example for version 2.1.2**

{% code lineNumbers="true" %}

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

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

#### Download License Files

1. Go to the [Cybus Portal](https://portal.cybus.io/).
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](https://docs.cybus.io/documentation/licensing#acquiring-license-keys).
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

## Phase 2: Installing Connectware on the Recipient PC

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

{% stepper %}
{% step %}

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

{% code lineNumbers="true" %}

```bash
cd /path/to/your/installation/folder
```

{% endcode %}
{% endstep %}

{% step %}

#### Start Docker

Ensure Docker is running on the recipient PC:

{% code lineNumbers="true" %}

```bash
sudo systemctl start docker
```

{% endcode %}
{% endstep %}

{% step %}

#### Load Docker Images

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

{% code lineNumbers="true" %}

```bash
# 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
```

{% endcode %}

**Example for version 2.1.2**

{% code lineNumbers="true" %}

```bash
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
```

{% endcode %}

**Result:** All Docker images are now loaded and available for use.
{% endstep %}

{% step %}

#### Run the Installer in Offline Mode

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

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% hint style="info" %}
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:

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

{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}
{% endstep %}

{% step %}

#### Configure the License

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

{% code lineNumbers="true" %}

```bash
nano docker-compose.yml
```

{% endcode %}

2. Locate the `system-control-server` service section and find the `CYBUS_LICENSE_FILE` environment variable.
3. Open your license file (`.lic`) and copy its entire content.
4. Paste the license content as the value for `CYBUS_LICENSE_FILE`:

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}

5. Save and close the file.

{% hint style="warning" %}
Ensure you paste the entire content of the `.lic` file, including the `-----BEGIN LICENSE-----` and `-----END LICENSE-----` markers.
{% endhint %}
{% endstep %}

{% step %}

#### Start Connectware

Start Connectware using Docker Compose:

{% code lineNumbers="true" %}

```bash
docker compose up -d
```

{% endcode %}

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

**Result:** Connectware is now running on the recipient PC.
{% endstep %}
{% endstepper %}

## 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`

{% hint style="warning" %}
For security reasons, change the default admin password immediately after your first login. See [Default Admin User](https://docs.cybus.io/documentation/user-management/users/default-admin-user) for more information.
{% endhint %}

### Uploading the License File

If prompted to upload a license file in the [Admin UI](https://docs.cybus.io/getting-started/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](https://docs.cybus.io/documentation/licensing#license-view) indicating that the system cannot connect to the license validation server at `https://graphql-server.cybus.io/graphql`.

{% hint style="info" %}
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.
{% endhint %}

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](https://docs.cybus.io/getting-started/connecting-your-first-machine)
* [Configure user management](https://docs.cybus.io/documentation/user-management)
* [Install additional services](https://docs.cybus.io/documentation/services/setting-up-and-configuring-services/installing-services)