Inheco Test Connector

A connector for the Inheco Test Connector built with the UniteLabs CDK.

Getting Started

Prerequisites

Ensure that Python 3.10 or newer is installed on your system. You can download Python from the official website python.org.

Installation

Create a Virtual Environment

It is highly recommended to use a virtual environment to manage the dependencies for your connector project. This keeps the dependencies for different connectors isolated from each other. Use the following command to create a virtual environment:

python -m venv venv

Activate the virtual environment:

• On Windows:

  .\venv\Scripts\activate.bat

• On macOS/Linux:

  source venv/bin/activate

If you are on a Windows machine, you may additionally wish to set the UNITELABS_CDK_APP environment variable to the connector's entry point. This can be done by running the following command:

set UNITELABS_CDK_APP=unitelabs.inheco_test_connector:create_app

Setting this environment variable will allow you to run varous CLI commands without providing --app unitelabs.inheco_test_connector:create_app every time.

Install Required Dependencies

Install the necessary Python packages into your active virtual environment. Use pip to download the connector along with its dependencies:

python -m pip install unitelabs-inheco-test-connector \
  --index-url https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple

If you are working with a private connector repository, authenticate pip to allow access:

python -m pip install unitelabs-inheco-test-connector \
  --index-url https://<username>:<password>@gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple

Configure the Connector

To get information about the configuration values for the connector simply run:

• On Windows:

  config show --app unitelabs.inheco_test_connector:create_app

• On macOS/Linux:

  config show

To create a configuration file for our connector we run:

• On Windows:

  config create --app unitelabs.inheco_test_connector:create_app

• On macOS/Linux:

  config create

Used as such this command will create a config.json in the current working directory. If you prefer to use yaml for your config file or would like to save the file to a different location, simply add the --path argument:

• On Windows:

  config create --app unitelabs.inheco_test_connector:create_app  --path <path to config>

• On macOS/Linux:

  config create --path <path to config>

The file that is created will be populated with default configuration values that you may now edit.

Note: The cloud_server_endpoint values are only necessary if you want to use the connector with the UniteLabs platform.

Verify the Installation

After installation, you can verify that everything works by starting the connector using the CLI tool included in the dependencies:

Note: This must be done in the activated environment setup in Step 1.

connector start --app unitelabs.inheco_test_connector:create_app -vvv

If you decided to create your configuration file at a non-default location, you can specify it with the --config-path or -cfg argument:

connector start --app unitelabs.inheco_test_connector:create_app -cfg <path to config> -vvv

In this way one can have multiple configurations for the same connector.

Usage

To interact with the running connector, we recommend using the SiLA Browser.

Encryption

To secure communication between the connector and its clients, you can enable TLS encryption. Start by installing the optional cryptography package for generating TLS certificates:

python -m pip install cryptography

To generate a pair of public and private keys, use the following command:

certificate generate

Without any arguments this command uses the default config location to get the connector's UUID and host name, required to generate TLS certificates. It will prompt you as to whether or not you want to update your config file to enable TLS encryption on your connector. This prompt can be suppressed with the use of the --non-interactive or -y flag, which will update the config file with paths to the locally created files without prompting, or with --embed or -e flag to write the file contents into the config file directly.

You can adjust your config file's host to reflect the machine's hostname, or set it to localhost if the connector should only be accessible locally.

If your config file was created at a non-default path, you can provide it with the --config-path or -cfg option:

certificate generate -cfg <path to config>

By default the generate command creates the cert.pem and key.pem files in your current working directory. You can customize the output directory with the --target argument.

If you choose not to update your config file with the paths to your certificates using --non-interactive or -y or to have the file contents saved directly in your config file with --embed or -e flag, you will have to modify the config file yourself to set the following values under sila_server:

• certificate_chain - the path to the cert.pem file
• private_key - the path to the key.pem file
• tls - a boolean that toggles on/off TLS encryption for the SiLA server

With your updated config file you can once again run:

connector start --app unitelabs.inheco_test_connector:create_app -vvv

Important: Never share the key.pem file with anyone. Only the cert.pem is required for clients to connect to encrypted servers.

Contribute

We welcome contributions to improve our connectors. Follow the steps below to set up your development environment.

Development Environment

We use uv for Python packaging.

Set Up the Environment

Install and configure uv:

pipx install uv

Note: requires uv>=0.6.8.

Install the Package

Clone the repository:

git clone https://gitlab.com/unitelabs/connectors/inheco-test-connector.git

Set up the development environment and start the connector:

uv sync --all-extras
uv run connector start -vvv

Note: By default, uv will sync all dependencies with every call to uv run CMD. To prevent this use uv run --frozen CMD or set the environment variable UV_FROZEN=true.

Install pre-commit Hooks

Set up pre-commit hooks to ensure code quality:

uv run pre-commit install

Running Tests

To run the test suite:

uv run pytest

To run tests with a specific version of python, e.g. Python 3.12:

uv run --python 3.12 --all-extras pytest

Dev-Mode

To improve the development experience, we recommend running the connector in developer mode. This will automatically reload the connector whenever changes to the source code are saved.

uv run connector dev --app unitelabs.inheco_test_connector:create_app

Contact

If you found a bug, please use the issue tracker.