# Installing Connectware (Docker) This guide walks you through installing Connectware on Docker using an installer script. The script automates the setup process and supports both interactive and silent installation modes. You can optionally configure Connectware to run as a systemd service for automatic startup. {% hint style="info" %} For environments without Internet access, see [Offline Installation](https://docs.cybus.io/documentation/installation-and-upgrades/installing-connectware/offline-installation-docker). {% endhint %} ## Prerequisites Before installing Connectware, make sure to meet the following requirements: * Connectware [license key](https://docs.cybus.io/documentation/installation-and-upgrades/licensing) is available. * You have an Internet connection to download Docker images from `registry.cybus.io`. * Docker and Docker Compose are installed and running on your host. * 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. * You are familiar with Docker. ## Preparing the Installer Script The installer script allows you to quickly install Connectware. 1. Download the installer script for the Connectware version that you want to install. * Download link for the installer script of the latest Connectware version: * To download the installer script for a specific Connectware version, use the following link and replace with the Connectware version: [https://download.cybus.io//connectware-online-installer.sh](https://download.cybus.io/%3CVERSION%3E/connectware-online-installer.sh) * For example, to download the installer script for Connectware 2.1.2, use the following link: \ \ In the example below, we will use the latest version of Connectware. {% code lineNumbers="true" %} ```bash wget -O ./connectware-online-installer.sh https://download.cybus.io/latest/connectware-online-installer.sh ``` {% endcode %} 2. Make the script executable: {% code lineNumbers="true" %} ```bash chmod +x ./connectware-online-installer.sh ``` {% endcode %} **Result:** You can now run the installer script to install Connectware. You can run the installer in two modes: * **Interactive mode:** Follow the prompts to configure your installation. See [Running the Installer Script](#running-the-installer-script). * **Silent mode:** Use command-line parameters for automated deployment. See [Running the Installation in Silent Mode](#running-the-installation-in-silent-mode). ## Running the Installer Script {% hint style="warning" %} You can run the installer script without administrator rights in most cases. However, sudo privileges are required in two scenarios: 1. When setting up Connectware as a systemd service (recommended). 2. When installing to a directory that needs elevated permissions. Since this guide demonstrates installing Connectware with systemd service integration, we will use sudo in the following commands. {% endhint %} 1. Run the installer script: {% code lineNumbers="true" %} ```bash sudo ./connectware-online-installer.sh ``` {% endcode %} 2. The installer displays the Connectware version. Press **Enter** to confirm. 3. Enter your desired installation directory, or press **Enter** to use the default path: `/opt/connectware` 4. The installer runs preflight checks to verify all system requirements are met. If any checks fail, review the [Prerequisites](#prerequisites) section and check if your system meets all requirements. If all requirements are met, the following output will appear: {% code lineNumbers="true" %} ```bash 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 reachable URL for Cybus docker-registry: [OK] Validating Docker installation: [OK] Validating Docker Compose installation: [OK] Validating that no former Connectware is running: [OK] Preflight checks finished successfully! ``` {% endcode %} 5. Enter your Cybus license key when prompted. If your license key is valid, you will see a success message. {% code lineNumbers="true" %} ```bash Verifying license key... Login succeeded. ``` {% endcode %} 6. Enter the ingress hostnames under which you will access Connectware. You can specify multiple values by separating them with commas. This allows you to define any hostnames, wildcard domains, and IP addresses that agents use to connect to Connectware. All values are added to the certificate's SAN field, enabling secure agent connections through any of the configured access points. You can change the hostnames later by setting the `CYBUS_INGRESS_DNS_NAMES` environment variable. {% hint style="info" %} If you are replacing the external Connectware CA certificate chain and manage `cybus_server.crt` manually, ensure that any DNS name with which you address Connectware or individual components is included. You can skip adding them to `CYBUS_INGRESS_DNS_NAMES`. {% endhint %} **Example** {% code lineNumbers="true" %} ```bash Ingress Hostnames [localhost]: my.company.tld ``` {% endcode %} 7. Choose whether to run Connectware as a systemd service. Without this, you must start Connectware manually after each system restart. In this guide, we press Enter to confirm. 8. Review the configuration summary and confirm your settings are correct. If you followed the steps in this guide, the following output will appear: {% code lineNumbers="true" %} ```bash 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] ``` {% endcode %} 9. The installer downloads the Connectware container images. After download completes, it checks for old container images from previous Connectware versions that can be safely removed ("pruned") to free disk space. The installer asks for confirmation before removing any images. {% code lineNumbers="true" %} ```bash ----------------------------------------- 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] ``` {% endcode %} 10. After confirming, the installer displays the image removal results and shows a success message with commands to manage Connectware. In our example, the following output will appear: {% code lineNumbers="true" %} ```bash Successfully installed Connectware! =================================== You can find the installation directory at /opt/connectware. In order to stop type: systemctl stop connectware ``` {% endcode %} ## 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 during installation. 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 %} ### Verifying the Installation To verify that Connectware is running correctly, use one of the following commands: **For Docker installations** {% code lineNumbers="true" %} ```bash docker ps | grep connectware ``` {% endcode %} **For systemd service installations** {% code lineNumbers="true" %} ```bash systemctl status connectware ``` {% endcode %} ### Managing the Connectware Service If you installed Connectware as a systemd service, you can manage it with the following commands: {% code lineNumbers="true" %} ```bash # Start Connectware systemctl start connectware # Stop Connectware systemctl stop connectware # Restart Connectware systemctl restart connectware # Check Connectware status systemctl status connectware # Enable Connectware to start on boot systemctl enable connectware # Disable Connectware from starting on boot systemctl disable connectware ``` {% endcode %} ## Running the Installation in Silent Mode The installer supports an automated deployment mode that requires no manual intervention. You can activate this by using either `-s` or `--silent` when [running the installation script](#running-the-installer-script). For silent installations, you must provide your license key through the `--license-key` parameter. By default, this method installs a basic version of Connectware to `/opt/connectware` and skips the systemd service setup. **Example with common options** {% code lineNumbers="true" %} ```bash sudo ./connectware-online-installer.sh \ -s \ -k your-license-key-here \ -d /opt/connectware \ -H "my.domain.com,192.168.1.100" \ -S ``` {% endcode %} This example installs Connectware in silent mode `-s`, uses a specific license key `-k`, installs to `/opt/connectware` directory `-d`, configures multiple hostname entries `-H`, and sets up the systemd service `-S`. If you need to customize your installation further, the script offers several configuration options. Run the installer with `--help` to view all available parameters. ## Updating SSL Certificates When you need to update your SSL certificates (such as after a Let's Encrypt renewal via `certbot` or when adding self-signed certificates), follow these steps: 1. Copy the new certificates to the container: {% code lineNumbers="true" %} ```bash docker cp -L ${PATH_TO_KEY_FILE} ${CONNECTWARE_CONTAINER}:/connectware_certs/cybus_server.key docker cp -L ${PATH_TO_CERT_FILE} ${CONNECTWARE_CONTAINER}:/connectware_certs/cybus_server.crt ``` {% endcode %} 2. The name of your Connectware container depends on the directory it was installed to and is rendered as `${CONNECTWARE_DIRECTORY}_connectware_1`. By default, Connectware is installed to `/opt/connectware/` which results in the container name `connectware_connectware_1`. 3. Restart the Connectware container to apply the new certificates. Replace `${CONNECTWARE_CONTAINER}` with the name of your Connectware container: {% code lineNumbers="true" %} ```bash docker restart ${CONNECTWARE_CONTAINER} ``` {% endcode %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cybus.io/documentation/installation-and-upgrades/installing-connectware/installing-connectware-docker.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.