Deployment

1. Prepare Docker

Deploying connectors via Docker presents an efficient solution for achieving operating system agnosticism, catering to a wide range of platforms including microcontrollers and computers. Leveraging Docker ensures consistent execution environments, mitigating compatibility challenges and facilitating a seamless deployment processes.

Before delving into the Docker deployment specifics, it's essential to understand the fundamentals of Docker and establish necessary prerequisites. More information on installing Docker on various operating systems is found in the Docker documentation.

These setup instructions are specific to a Docker installation under Unix.

Set up Docker's apt repository:

sudo apt install vim ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Install the additional Docker packages:

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Grant the user (default: unitelabs) access to Docker:

sudo usermod -a -G docker unitelabs

Configure Docker to start on boot with systemd:

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

2. Authenticate Docker

This step is required for UniteLabs connectors: To enable Docker to pull the connector image, Docker needs access to the UniteLabs Artifactory: A username (Tenant UUID) and password (GitLab deploy token) are required.

• Username: 32 characters separated by dashes in UUID4 format, e.g. 56ae938f-484c-41cc-ae54-e4f9b8814fb7.
• Password: 22 characters separated by dashes, e.g. ahjt-Lk-e1swOPZcWYYGh-mKJ

Authenticate Docker using the command below. This allows the docker daemon to pull private Docker images (You may need to restart the machine!). The Docker daemon must be running for this!

sudo reboot
echo "<password>" | docker login registry.gitlab.com --username <username> --password-stdin <password>

3. Create a Docker Compose file

Docker Compose is used to manage deployments more efficiently, especially when dealing with the deployment of multiple connector applications on the same system. Problems that are tackled by using Docker Compose include automatic restarts on connector crashes or reboots as well as log rotation and memory management.

When docker is available and installed correctly, create a docker-compose.yml file. This is typically done by a UniteLabs representative. The default path for this file is /home/unitelabs/docker-compose.yml.

services:
  hamilton-microlab-star:
    image: registry.gitlab.com/unitelabs/connectors/hamilton-star:2cd5f877
    restart: always
    environment:
      ENVIRONMENT: production
      SILA_SERVER__HOSTNAME: 0.0.0.0
      SILA_SERVER__PORT: 50051
      SILA_SERVER__UUID: e1c7147d-a11f-4ac5-9518-df4f62ac6e1c
      CLOUD_SERVER_ENDPOINT__HOSTNAME: ca91c49c-ca1-40b7-9b93-46b69861f367.unitelabs.io
      CLOUD_SERVER_ENDPOINT__PORT: 443
      CLOUD_SERVER_ENDPOINT__TLS: True
      SIMULATION: false
    privileged: true
    volumes:
      - /dev/bus/usb:/dev/bus/usb

Depending on the connector, some resources of the host system must be made available such as serial and USB ports. Apart from the Server and cloud-endpoint specific environmental variables, the connector may accept additional environmental variables. These are generally documented in the connector documentation.

The connector image is pulled from the UniteLabs GitLab container registry. A version can be specified using the trailing hash of the registry URL. The latest tag can be used to pull the most recent stable image. Multiple connectors (services) can be defined in the same docker-compose file.

4. Manage connector containers

Start the containers with:

docker compose up -d

Running containers can be listed with docker ps. The logs of each container can be accessed with docker logs <container ID>. Individual containers can be restarted and stopped using the basic Docker commands docker stop <container ID> and docker restart <container ID>.

While Docker containers are the preferred option to deploy connectors, certain applications may require the installation of a connector on a machine with a Windows operating system. In these cases, it is often advantageous for the connector to start automatically upon user login, such as after a system restart.

Setup

This installation option requires a Python installation with the appropriate package manager (either poetry or uv). The connector repository can be cloned to the machine using Git or, if Git is unavailable, downloaded manually from GitLab. Access to connector repositories must be granted by UniteLabs and the deployment token and further credentials need to be set up accordingly. Reach out to the UniteLabs support for further help (support@unitelabs.io). Projects which contain a poetry.lock are managed by Poetry: within the connector root directory, open a command prompt window and run poetry install. Projects which contain a uv.lock are managed by UV: within the connector root directory, open a command prompt window and run uv sync.

Register service with Windows Startup

If the connector is specifically designed for Windows, it may already include two .bat files in the root folder: register_login_item.bat and gen5_service.bat. Executing register_login_item.bat with administrative privileges will set up the connector to start upon login.

If this worked the rest of this tab can be ignored.

Debug: The files are not present

Should these files be absent, they can be created manually. Create two files named register_login_item.bat and gen5_service.bat, ensuring they are saved with the .bat extension. Open these files in a text editor (e.g. VS Code, PyCharm, Notepad++) and enter the following content:

call <runner> run connector start

where is the name of the environment management tool the project is using, e.g. poetry or uv.

And:

  @echo off
  setlocal

:: Define variables
set "BAT_FILE=gen5_service.bat"
set "SHORTCUT_NAME=gen5_service.lnk"
set "CURRENT_DIR=%~dp0"
set "STARTUP_FOLDER=%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup"

:: Check if the batch file exists
if not exist "%CURRENT_DIR%%BAT_FILE%" (
    echo Error: %BAT_FILE% does not exist.
    exit /b 1
)

:: Create the shortcut
set "VBS_SCRIPT=%TEMP%\create_shortcut.vbs"
echo Set oWS = WScript.CreateObject("WScript.Shell") > "%VBS_SCRIPT%"
echo sLinkFile = "%CURRENT_DIR%%SHORTCUT_NAME%" >> "%VBS_SCRIPT%"
echo Set oLink = oWS.CreateShortcut(sLinkFile) >> "%VBS_SCRIPT%"
echo oLink.TargetPath = "%CURRENT_DIR%%BAT_FILE%" >> "%VBS_SCRIPT%"
echo oLink.WorkingDirectory = "%CURRENT_DIR%" >> "%VBS_SCRIPT%"
echo oLink.WindowStyle = 7 >> "%VBS_SCRIPT%"
echo oLink.Save >> "%VBS_SCRIPT%"

cscript /nologo "%VBS_SCRIPT%"
del "%VBS_SCRIPT%"

:: Move the shortcut to the Startup folder
if not exist "%STARTUP_FOLDER%" (
    mkdir "%STARTUP_FOLDER%"
)

move "%CURRENT_DIR%%SHORTCUT_NAME%" "%STARTUP_FOLDER%"

echo Shortcut for %BAT_FILE% created and moved to startup folder.

:: Display message and wait
echo Registration complete
timeout /t 10

endlocal
exit /b 0

Debug: register_login_item.bat did not work

The gen5_service.bat file must still be created with the same script provided in the automatic setup.

call <runner> run connector start

where is the name of the environment management tool the project is using, e.g. poetry or uv.

After creation, create a shortcut by right-clicking the gen5_service.bat file and selecting ‘Create shortcut‘. On Windows 11 this can be found under ‘Show more options' > ‘Create shortcut'.

Next, press Win + R, type shell:startup, and press enter to open the startup folder. Drag and drop the previously created shortcut into this folder to complete the setup. This process ensures the connector will start whenever the system logs in a user.