Running with Docker

Or, I see you have some sense

Source code here https://github.com/Looselab/Icarust/!

Quick start

git clone https://github.com/LooseLab/Icarust_docker.git
cd Icarust_docker
docker compose run --service-ports icarust

In order to run with docker, docker engine > 3.20 and docker compose must be installed. Respective instructions for Docker, and docker compose. The compose instructions are for linux alone, I believe that you need to install docker desktop for MacOS in order to have compose.

❗ Due to MacOS using virtualisation, file writing is very slow. It may be better for MacOS users to run natively. See here.

Whilst this is possible on Windows, linux and MacOS, I only have access to one of these OSs, and the volume bindings in the docker-compose.yml are linux specific. Pull requests welcome 👀. See below in the volumes explanation for how to change this.

To run with simple defaults, enter the directory containing your docker-compose file and simply:

docker compose run --service-ports icarust

NB. The flag --service-ports opens up the ports on the docker container, so that the minKNOW API can connect. Otherwise, docker compose run ignores opening ports on the container.

Let's break down what happens here. The contents of docker-compose.yml are as follows -

version: "3.8"
services:
  icarust:
    image: adoni5/icarust:latest
    init: true
    build:
      context: ..
      dockerfile: ./docker/Dockerfile
    ports:
      - "10000:10000"
      - "10001:10001"
    volumes:
      - ./configs:/configs
      - ./squiggle_arrs:/squiggle_arrs
      - ./output:/tmp

So when we call docker compose run, the image listed at adoni5/icarust:latest is pulled, the required ports are exposed, and the required volumes are mounted.

Ignoring the build section as out of context, (read more here if you wish to understand), this file effectively defines the icarust service.

icarust:
  image: adoni5/icarust:latest
  init: true

If the docker image for icarust is not found locally, one is pulled from hub.docker.com, from the adoni5/icarust repository. init:true means that icarust is run as the top level process, or PID:1. This allows it to respond to signals that are sent to the running container, such as KeyboardInterrupt to stop the process.

ports:
  - "10000:10000"
  - "10001:10001"

This exposes the ports 10000, and 10001 from inside the container to the host machine you are running docker on. The 10000 port is the port that the GRPC manager is running on, and the 10001 port is the port that the fake sequencing positions GRPC server is listening on.

volumes:
  - ./configs:/configs
  - ../squiggle_arrs:/squiggle_arrs
  - ./output:/tmp

This final section binds the listed directories on the left of the : of each line to the directories inside the container given on the right. This was the reasoning behind using compose to manage this container as it made the execution command much tidier.

- /configs contains the Simulation profile tomls and the config.ini file to pass parameters to the sequencer.
- /sqiggle_arrs. Pregenerated squiggle must be placed here.
- ./output:/tmp binds the host directory `output` to the `/tmp` directory in the container. This is where the squiggle is written to by default, so it is then available to the host system for analysis.

TLS Certs

The TLS certs are bundled in the image - any config.ini that you pass should set the TLS section as follows -

[TLS]
cert-dir = /static/tls_certs/

Profile Tomls

For actual simulation settings, see the Icarust Readme.

Pass different arguments to Icarust

The default arguments are defined in the main Icarust repo, in docker/Dockerfile. They are set in the Dockerfile, and are

-v -s /configs/config.toml

In order to change the Simulation Profile we are running, simply provide alternatives on the end of the docker compose run icarust command. For example:

docker compose run icarust -vv -s /configs/<your_config_here>.toml

If you wish to change the number of channels or where the certificate path is located, these values can be edited in configs/config.ini. If the rpc certificates are changed, these will have to be changed to the respective values in the docker-compose.yml. For example if the certificates were changed to /opt/ont/WinKNOW/what_certs, the docker-compose.yml would become

volumes:
  - ./configs:/configs
  - /opt/ont/WinKNOW/what_certs:/opt/ont/WinKNOW/what_certs
  - ../squiggle_arrs:/squiggle_arrs
  - ./output:/tmp

Troubleshooting

Permission Shenanigans

By default the container runs with a User ID of 1000. If you are the primary user of this computer, this is likely to be you! This will not leave you with any problems. However If you are not the primary user, or you are running on a server with other user accounts on, you will not be able to wrtie out signal. In order to fix this, you can set the --user argument on the docker compose run command.

⚡ Disclaimer, I have no idea how this works on windows!

Find out who you are by running the id command on the command line. Example output for ubuntu 20:

uid=997(adoni5) gid=1000(adoni5)```

So I can see here my user id is 997. In order to run with permissions to interact with the output FAST5 files, you can run the starting command as:

docker compose run --user 997 --service-ports icarust [optional arguments to Icarust]