4. Tutorial (Docker)

Please download the files in https://github.com/rlrq/MINORg/tree/master/examples. In all the examples below, you should replace “/path/to” with the appropriate full path name, which is usually to the directory containing these example files.

4.1. Running MINORg image as container

If you pulled rlrq/minorg, run the MINORg image as a container using:

docker run -ti rlrq/minorg

Otherwise, if you pulled rlrq/minorg-lite, use:

docker run -ti rlrq/minorg-lite

This starts a linux bash session in a directory called ‘/minorg_docker’, so you should see a command prompt like this:

root@1b2a51c79131:/minorg_docker#

The cryptic alphanumeric string between @ and : is the container ID (in this example, it’s 1b2a51c79131). Docker will also automatically assign a more human-readable name to the container. To find this human-readable name, start a new terminal session (not in a Docker container) and execute:

docker ps

You should see something like this:

CONTAINER ID   IMAGE     COMMAND   CREATED          STATUS          PORTS     NAMES
1b2a51c79131   minorg    "bash"    31 seconds ago   Up 29 seconds             great_hodgkin

The container name can be found in the last column.

Alternatively, you can also give container a name by running the image using:

docker run -ti --name my_minorg rlrq/minorg

In the above example, the newly created container’s name will be my_minorg.

4.2. Preparing files

Within the container, unzip the example files using:

root@1b2a51c79131:/minorg_docker# unzip examples.zip

If you pulled rlrq/minorg, unzip the Cdd database and return to the starting directory using:

root@1b2a51c79131:/minorg_docker# cd db
root@1b2a51c79131:/minorg_docker/db# unzip Cdd.v3.18.zip
root@1b2a51c79131:/minorg_docker/db# cd ..

Note that the path to the Cdd database is: /minorg_docker/db/Cdd.v3.18/Cdd

4.3. Importing files

As a Docker container is isolated from the host system, files need to be imported into the container, which can be achieved using docker cp. To copy a single file, start a new terminal session (not in a Docker container) and execute:

docker cp /path/to/file.txt <container ID or name>:/minorg_docker/path/to/destination.txt

To copy a directory, use:

docker cp /path/to/directory <container ID or name>:/minorg_docker/path/to/destination

4.4. Running MINORg

At this point, you can either follow the command line tutorial starting from Setting up the tutorial to run MINORg in the command line of the container, or start an interactive Python session (Python 3.9 is installed in the container) and follow the Python tutorial starting from Setting up the tutorial to run MINORg in Python.

4.5. Exporting output files

As previously mentioned, the Docker container is isolated from the host system. You may export the files output by MINORg in the container to your system using docker cp again. To export a single file, use:

docker cp <container ID or name>:/minorg_docker/path/to/file.txt /path/to/destination.txt

To export a directory, use:

docker cp <container ID or name>:/minorg_docker/path/to/directory /path/to/destination

4.6. Exiting the container

When you’re done, you may exit the Docker container using ctrl-D or by typing exit.

4.7. Reusing the container

Assuming that you did not remove the container, you can restart an exited Docker container session using:

docker start -i <container ID or name>

Your files will still be there.

4.8. Removing the container

If you do not wish to reuse the container, you can delete it using:

docker rm <container ID or name>

4.9. Docker docs

For more on Docker, you may check out Docker’s website: https://docs.docker.com/