Getting Started - heros-boss 0.5.1 documentation

Skip to content
Back to top
View this page

# Getting Started

## Possible Configuration Sources

Device configuration data can be supplied to BOSS from various sources.

For testing purposes or isolated BOSS instances, you can directly supply a JSON file with the device configuration inside. Run BOSS with the absolute path to the JSON file:

    python -m boss.starter --u file:///absolute/path/to/file.json

For a production setup, we recommend using a network based database like CouchDB. This has the advantage, that all configurations are at a central point and are easy to maintain.

    python -m boss.starter -u http://<user>:<pw>@<couchdb_host>:5984/my-boss/http-test

See CouchDB for more details.

BOSS can also load the configuration from environment variables

    export BOSS1={"_id": "docker-env-ftp","classname": "ftplib.FTP","arguments": {"host": "ftp.us.debian.org"}}
    python -m boss.starter -e BOSS1

This can make sense for example for docker based portable deployments. An example of this can be found in the Docker compose file below.

Hint

BOSS uses urllib to parse the url specified by the `-u` argument, which supports many more url schemes than listed here. This means you can use also completely different endpoints to host your configuration for BOSS like ftp or svn, the only requirement is that there is a valid JSON configuration string at the end.

## Installing/Deploying BOSS

A convenient way to deploy BOSS is inside of a docker container. You can find pre-build containers images in our docker registry.

Hint

You can also build the BOSS docker image yourself from the Dockerfile in the repository: `docker build -t atomiq/boss .` By building the docker image yourself, you can modify the docker image and add for example custom device vendor libraries or similar.

A BOSS docker service can be started with the following compose file

    services:
      httpclient:
        image: registry.gitlab.com/atomiq-project/boss:latest
        restart: always
        network_mode: host
        environment:
         - |
           BOSS1=
           {
            "_id": "docker-env-ftp",
               "classname": "ftplib.FTP",
               "arguments": {
                    "host": "ftp.us.debian.org"
               }
           }
        command: python -m boss.starter -e BOSS1

Additionally, also specifying a file or URL is possible, such that (mounted) json files in the docker container or web URLs can be used as configuration sources. Note that the `-e` and `-u` options can be specified in the command line multiple times to define several objects that should be instantiated by the BOSS.

BOSS can also be installed locally via pip:

Hint

We recommend using uv to maintain an enclosed python environment.

    uv pip install heros-boss

    pip install heros-boss

Now you are ready to go! You can get an overview over the command line arguments of boss by running

    uv run python -m boss.starter --help

    python -m boss.starter --help

## Additional Dependencies in Docker

Due to the large variety of devices supported by herosdevices, it becomes intractable (and sometimes legally troublesome) to have all dependencies for every device installed in the the base image. It might thus be necessary to extend the docker image by required third party libraries in one of the following ways:

BOSS can install dependencies from various sources during container creation. You can specify these dependencies in the docker-compose file as the following minimal example shows:

docker-compose.yaml

    services:
      myboss:
        image: registry.gitlab.com/atomiq-project/boss
        restart: always
        network_mode: host
        environment:
          - BOSS_PIP_PKGS=toptica-lasersdk pyserial
          - BOSS_APT_PKGS=libftdi1
          - PVCAM_SDK_PATH=/opt/pvcam/sdk # For pvcam installed via script below
        command: python -m boss.starter --log debug --expose
        volumes:
          - ./my_pkgs/:/etc/boss/

- `BOSS_PIP_PKGS`: Packages specified here are installed into the environment via pip. Every valid pip package syntax is usable (Notably `git+https://...`). Here pyserial and toptica-lasersdk are installed.

- `BOSS_APT_PKGS`: Packages specified here are installed via the apt package manager. The base image is based on debian so everything debian offers can be added here. Here `libftdi1`.

  Note

  Packages via `apt` are installed first so that they are available during the installation of `pip` packages.

- Local Packages: The starter looks for files with the extensions `.boss.sh` in `/etc/boss`. In the example the folder, `./my_pkgs` residing in the same directory as the compose file is mounted to that location. The following scripts install the pvcam software.

  pvcam.boss.sh

      # Install prerequisites
      apt-get update && apt-get install -y sudo git

      # Install the vendor library itself
      # We have to agree to some licenses here so we use the "yes" command.
      # The EUID=1 is a little hack to trick the installer into thinking we're not root.
      /bin/sh -c 'yes | EUID=1 /bin/bash ./pvcam/pvcam__install_helper-Ubuntu.sh'

      # Remove build files after installation to make image a bit smaller
      rm -rf /pvcam

      # We need to point the python api to the correct library path
      export PVCAM_SDK_PATH="/opt/pvcam/sdk"
      # Install python API
      pip install --break-system-packages PyVCAM

If you want to generate a permanent image with your drivers, you have to extent the `BOSS` base image.

Note

Note that you have to repeat this process for every update of the base image. We therefore recommend the BOSS native method for most use cases.

The following example shows this process at the example of `herosdevices.hardware.teledyne.pvcam.PvcamCamera`:

- Create a new a directory and download and unzip the binary drivers. There should now be two folders `pvcam` and `pvcam-sdk` among others.

- Create `Dockerfile` with the following content:

      # Base image to expand
      FROM registry.gitlab.com/atomiq-project/herosdevices

      # Copy the vendor library into the container
      COPY pvcam /pvcam

      # Install prerequisites
      RUN apt-get update && apt-get install -y sudo git

      # Install the vendor library itself
      # We have to agree to some licenses here so we use the "yes" command.
      # The EUID=1 is a little hack to trick the installer into thinking we're not root.
      RUN yes | EUID=1 /bin/bash /pvcam/pvcam__install_helper-Ubuntu.sh

      # Remove build files after installation to make image a bit smaller
      RUN rm -rf /pvcam

      # We need to point the python api to the correct library path
      ENV PVCAM_SDK_PATH="/opt/pvcam/sdk"
      # Install python API
      RUN pip install --break-system-packages PyVCAM

  Tip

  The docker container runs a debian system. Vendor libraries for ubuntu are therefore mostly compatible.

- Run `sudo docker buildx build --tag herosdevices:pvcam .`

  Tip

  The `:pvcam` is the tag name of the image. You should choose something to make it descriptive of what you put in the image.

- In your docker compose files, replace the `registry.gitlab.com/atomiq-project/herosdevices:latest` by `herosdevices:pvcam`.