Skip to content

Roxie in Docker

There exists a containerized Roxie version to operate within a docker environment.

Setup: Installing Docker

To use docker, install it from the official webpage and follow the installation instructions.

Enabling virtualization

A common error while installing docker is that it cannot run virtual machines due to restrictions set up in BIOS. For this, virtualization technology needs to be set up in BIOS/UEFI. This help desk article gives hints for different vendor Systems.

Login to gitlab registry

The Docker images are using the Cern gitlab registry. To gain access to the roxie images, you can ask the roxie-support to add you to the project, or generate an access token if you don't have a CERN gitlab account. Then, in a terminal, type the following 

docker login gitlab-registry.cern.ch -u <gitlab_user> -p <password>

Starting the container

After the registry is set up, the Docker image can be downloaded and started. The easiest solution is using a docker-compose file.

Using docker-compose

With docker-compose we can write a configuration file to setup the roxie image, and also bundle it with other services in a composed environment. An example docker-compose.yml file would look like this: 

version: "3.8"
services:
  #...
  #...
  roxie:
    image: gitlab-registry.cern.ch/roxie/roxie-deployment/roxie_full:latest
    command: 
        - -v
        - -r
    ports:
      - "5901:5901"
      - "6901:6901"
      - "8080:8080"
    container_name: roxie
    volumes:
      - <Path to local folder>:/home/roxie/data # Map local folder

<Path to local folder> is the exchange directory between the host system and the roxie container. The following examples show valid volume definitions (especially for folders with space): 

      - ./local_folder:/home/roxie/data # Map local folder in Linux
      - /home/user/roxie:/home/roxie/data # Map global folder in Linux
      - C:/Users/user/roxie_data:/home/roxie/data # Folder in Windows
      - "C:/Users/user/roxie folder with space:/home/roxie/data" # Folder in Windows with space

To start the service, from a terminal, in the folder of the docker-compose.yml file, type

docker-compose -d up

This will run all services, and start the roxie image. To access ROXIE, open a webbrowser to http://localhost:6901/vnc.html?password=roxiepw&autoconnect=true.

To stop, from the same folder, type

docker-compose down

Manually start Docker container

Roxie offers two containers: A minimal, barebone version (only roxie installed), and a full package, including VNC server, and a REST API to communicate via the container.

Containers are tagged by roxie versions, e.g latest, 23.9.0.b17, master,

To start an image, type in a terminal

docker run [-d|-it] [-p <local port>:<image port>] [-v <local folder>:<image folder>] <image> [options]

With the following options:

  • `-d|-it`` Run in detatched mode (process returns immediately, runs in the background) or interactive (open a terminal)
  • -p Forward a port from the container to the host system (needed for VNC server/client or REST API)
  • -v Mount a folder from the host to the image
  • image The name of the image
  • [options] Options forwarded to the image

For example, a session to minimal roxie would be opened as follows:

docker run -it -e DISPLAY=:0 -v /tmp/.X11-unix:/tmp/.X11-unix -v ./roxie_testcases:/roxie_testcases gitlab-registry.cern.ch/roxie/roxie-deployment/roxie_minimal:latest

Which should prompt a terminal to use within a roxie environment.

The roxie_full image provides the following additional options, which can be forwarded to the image (after the image name in the command line):

  • -d Debug output
  • -e <command> Execute command
  • -v Run vnc server and client
  • -r Run Rest API
  • -h Print out help

To open a Full roxie Session with VNC/REST active, use the following:

docker run -d -p 5901:5901 -p 6901:6901 -p8080:8080 -v <local folder>:/data gitlab-registry.cern.ch/roxie/roxie-deployment/roxie_full:latest -v -r

Which starts the roxie image, a VNC connection and a Web Socket with the Rest API:

Integrated Roxie + Python Environment

We are working on a all-in-one composed docker envirnoment including Roxie, python APIs and a jupyter environment for running Roxie from python. If you're interested, you can find a snapshot of this setup on Gitlab.