Running the BOINC jobs directly in a Docker container

[Tanya1515]

Background

According to issue 5512 running BOINC jobs directly in a Docker container is an up to date task. However, writing a Docker wrapper is not the only way to solve the problem. Our approach of adding an opportunity to run BOINC jobs directly in a Docker is based on boinc-server-docker. It allows to automatically set up a BOINC server in Docker with a special module boinc2docker. Boinc2docker is a plugin written in Python, which allows sending Docker workunits to BOINC clients. The execution of Docker containers takes place inside virtual machine of Virtualbox hypervisor.

Our solution consists of two parts:

1. BOINC source code modification to add check for Docker/Docker compose is installed and available for execution on BOINC client;

2. New version of module boinc2docker, that allows to run the BOINC jobs directly in a Docker.

Advantages of the approach:

1. The solution doesn’t depend much on BOINC source code, so extending the functionality is much easier. As an example, if adding an opportunity running BOINC jobs in Podman containers is required, it is needed to create a check function for Podman on the client side and add some minor modifications in module boinc2docker;
2. The user is not restricted by the functionality of Docker wrapper, so he can run any Docker/Docker compose command he wants.
3. Creating jobs in BOINC requires a high level of knowledge about how the system works. Also the process can take significant time. However, with the help of module boinc2docker the time and effort, that user spend on creating BOINC application and sending BOINC workunit, can be significantly reduced;
4. In the approach it is much easier to run Docker containers with GPU support, as user only has to write right command.

Docker plan class

The source code of BOINC has been modified to filter and send BOINC jobs to volunteer hosts where Docker and Docker compose (old/new version) are installed and available for execution. The check is implemented for both UNIX OS and Windows (also checking for presence of WSL 2). New parameter docker is available for use in plan class. With the help of the flag volunteer machines with Docker installed and available for execution will be filtered out. The <docker_compose_version> flag is used to identify the version of Docker compose. Acceptable values: v1 - for Docker-compose (old version), v2 - for Docker compose (new version), v1v2 or v2v1 - if both versions of the technology are required. The source code of modified BOINC (branch: boinc_docker).

Restriction: BOINC client must have the same version of source code as BOINC server, if user wants to send BOINC jobs with Docker.

New version of boinc2docker

New version of boinc2docker is a python module that automates the process of creating BOINC application and sending BOINC workunit. Bash script is considered as executable code for UNIX OS, while bat-file is for Windows. In both cases, the script is run under BOINC wrapper. The content of bash/bat file includes commands to run user-written bash script, which in turn initiates Docker container work. The user's bash script is passed along with the other input files of the BOINC workunit.

Steps for BOINC applications creation in boinc2docker:

1. Create plan_class_spec.xml according to user requirements. Flag docker is added automatically;

2. Create the directory hierarchy for new applications;

3. For every supported platform:

   • Download suitable BOINC wrapper for the platform;
   • In the same directory a file version.xml is created:

      <?xml version="1.0" ?>
          <version>
              <file>
                      <physical_name>wrapper_26015_x86_64-pc-linux-gnu</physical_name>
                      <main_program/>
              </file>
              <file>
                      <physical_name>test_docker</physical_name>
                      <logical_name>test_docker</logical_name>
              </file>
              <file>
                      <physical_name>test_docker.xml</physical_name>
                      <logical_name>job.xml</logical_name>
              </file>
          </version>

   • Bash/bat script is added to the same directory:
     For windows (bat script):

          wsl chmod 777 %1
     
          wsl bash %1
     

     For UNIX OS (bash script):

          #!/bin/bash					
     
          chmod 777 $1
     
          ./$1
     

   • Job.xml is created too:

     <?xml version="1.0" ?>
         <job_desc>
             <task>
                     <application>test_docker</application>
                     <command_line>boinc_docker</command_line>
             </task>
        </job_desc>

4. Record about new BOINC application is added to project.xml file;

5. For updating information about application and application versions bin/update_versions and bin/xadd are run from code;

Creating a BOINC application is followed by sending a new BOINC workunit (also part of boinc2docker module):

1. Handling the Docker image. Downloading a Docker image to a volunteer node can be done in one of two ways:
   • With the help of docker pull command in a user bash script;
   • Docker image is downloaded to the BOINC server and sliced into layers. Each layer is packed into an archive and then passed to the BOINC client along with other user input files;
2. Processing the user bash script with commands to run Docker containers. If the Docker image is passed as a collection of archives, code for unpacking the archives and loading the Docker image (docker load command) is added to the script;
3. The command ./bin/stage_file is executed for all input files;
4. The template describing all user input files of the BOINC workunit is generated in a temporary directory;
5. A template describing files with computation results is created in the directory “templates” of BOINC server;
6. Start BOINC workunit with bin/create_work;
7. The user is given an identification number of the BOINC workunit, which is used to find the computation results files.

The following figure presents the process of sending a BOINC workunit to a volunteer host.

List of the module parameters that are available for user to change are presented below:

• appname - BOINC application name;
• new_app - flag for creating new BOINC application. If user wants to send new BOINC workunit of already created BOINC application, the parameter must not be used;
• image - list of user Docker images. The flag is used, if user wants to send a Docker image as several archives;
• docker_registry - list of docker login options for using users' docker registry: user, password, docker registry name. The parameter must be used with image;
• input_files - list of user input files names, except bash script and archive of the Docker images;
• output_files_names - list of files with computational results;
• bash_script_path - path to users' bash script;
• plan_class_name - plan class name;
• plan_class_new - flag for creating new plan class;
• use_docker_compose - parameter for plan class, that requires docker-compose (old version) to be installed and available for execution on BOINC client;
• use_compose - parameter for plan class, that requires docker compose (new version) to be installed and available for execution on BOINC client;
• gpu_type - BOINC plan class parameter (gpu type);
• ngpus - BOINC plan class parameter (amount of gpus);
• min_gpu_ram_mb, gpu_ram_used, driver_versions, cuda_versions, use_ati_libs, use_amd_libs, min_ncpus, max_threads, mem_usage_base_mb, mem_usage_per_cpu_mb - BOINC plan class parameters;

Therefore, to run a BOINC task using Docker containers and GPUs, the following steps are necessary:

1. Create a bash script on the configured BOINC server:

2. Execute the command ./bin/boinc2docker_create_work with the necessary parameters:

3. As a result, the user will receive a file with computations on the BOINC server in the upload directory:

Similarly, the launch of a BOINC workunit that uses docker-compose or docker compose is initiated. The user creates a YAML configuration file (compose.yaml) on the BOINC server and passes it as an input file using the input_files parameter.