Prepare a Docker image for the MiniZinc Challenge 2020

• MiniZinc Challenge
• »Challenge 2020
• »Docker Image Preparation

1 Introduction

This document lists the steps for setting up a solver submission for the MiniZinc Challenge 2020.

Like last year, we provide a docker image www.docker.com that the participants have to extend with their solver to take part in this year challenge.

In comparison to virtual machines as used in the previous challenges, docker provides a number of advantages:

• No predefined disk space limitation.
• No OS installation from scratch.
• Different clusters, e.g., Amazon Web Services (AWS), support docker.
• Only the difference between the provided image and the extended image needs to be uploaded.
• Easy to extend the image by a configuration file that can be re-used for future challenges.
• A clean state for solver run.
• Higher automatisation of the execution of solvers.

2 Brief Overview of the Concept of Docker

There are two main concepts docker image and docker container. Intuitively, a docker image is a OS that cannot change its state and cannot run directly, but can be shared with other through docker hub. Opposed to an image, a docker container is an instance of an image that can be changed and run as it would be your local machine. Multiple containers of the same docker image can be created and run independently. The current state of a docker container can be stored as a docker image and then shared with others. The stored image is the image that the container was created from plus the changes made during its executing.

3 Installation of Docker

Docker CE (Community Edition) is available for different operation system including Ubuntu, Mac OS X, and Windows. For example, go to Docker For MacOS, Docker For Windows, and Docker For Ubuntu. Read through all instructions and requirements on the webpage before you start the installation. Follow the installation steps provided on that page. You can test your installation by executing following command.

docker run hello-world

4 Registration to Docker Hub

For the submission process, you need to create an account to Docker Hub, in which you upload your submission (docker image). Docker hub provides you the facility to store your image in a repository with a tag. Note that you can create one private repository for free, which you can share with the MiniZinc Challenge Team. Note too that a repository is created via the web pages.

5 MiniZinc Challenge 2020 Docker Image

The docker image was created via configuration file called Dockerfile (download MiniZinc Dockerfile here) and is available at the repository minizinc/mznc2020 with the current tag latest. Pull the repository via command line by this command.

docker pull minizinc/mznc2020

The image contains a minimal installation of Ubuntu 18.04 and MiniZinc 2.4.3, which is installed in the /usr/local/bin directory. In the MiniZinc directory /minizinc, there are the three shell scripts mzn-exec-fd (for the FD class), mzn-exec-free (for the FREE class), and mzn-exec-par (for the PAR class) (these are the same as in previous MiniZinc Challenges). If you sumit a MiniZinc solver then you need to modify them accordingly. If you submit a FlatZinc solver then you may need to add, modify, or remove parameters that are used for calling your FlatZinc solver. In the case of a FlatZinc solver, there must an executable at /entry_data/fzn-exec and the solver's MiniZinc library must be located in the folder /entry_data/mzn-lib. You should install your solver in the directory /entry_data.

If you want to inspect the image via a bash shell then create a container, interactively run the container, and delete the container after execution via this command.

docker run -it --rm minizinc/mznc2020 /bin/bash

6 Preparation of the Solver Submission

There are two ways to prepare a solver submission. One way is to use a configuration file (dockerfile), which directly creates the docker image with the solver installed and the other way is to create an instance, install the solver via command line, and then store the instance state as a docker image. The first way is preferred, because it can be re-used (with one or two modification) for a future submission and the creation is automatically via one docker command.

6.1 Dockerfile

There are two ways to build an image from a dockerfile. The first way is to specify a folder that includes the dockerfile named Dockerfile and any other files required for creation the image and the second way is to use standard in (stdin). In both cases, the starting point is a dockerfile. For example, we use dockerfiles to create the MiniZinc submission for Chuffed (download Chuffed dockerfile here) and Gecode (download Gecode dockerfile here).

6.1.1 Creation of a Dockerfile

Dockerfiles contain a sequence of statements where FROM, ADD, RUN, COPY, and ENV are the most important ones and briefly describe here. Please look at the dockerfiles that are linked above for the MiniZinc Challenge, Chuffed, and Gecode image. They contain many examples for these statements.

FROM <repository>:<tag> [AS <build stage name>]

The statement FROM specifies from which repository and tag an image is created from, and starts a new build stage. For example, ubuntu:16.04 for the Ubuntu 16.04 LTS image. For multi-stage builds, you want to specify a build stage name that you can refer to in later build stages. The last stage is the image that will be created. All other statements will modify the build from the latest FROM statement. The last stage statement must be FROM minizinc/mznc2020.

ADD <Source File> <Target File>

The statement adds a file from local directory (when image is built via folder option) or from Internet and stores it in the build as specified in Target File.

COPY --from=<build stage name> <Source Path/File> <Target Path/File>

The statement copies a path or files across from a previous build stage specified in build stage name to the current build stage.

RUN <Command>

The statement executes any command available in the build. Long lines can be broken up by ending a line with this character \.

ENV <Environment Command>

The statement sets up an environment variable in the build.

6.1.2 Via Folder

Build an image from a docker file with a context (folder must contain a file named Dockerfile). In this way, you can add files in the context to your build. Choose an appropriate repository name and tag.

docker build -t <repository name>:<tag> <path Dockerfile>

6.1.3 Via Standard In

Use this command in a terminal in Mac OS X or Linux distributions. You can freely chose the name of your dockerfile. Choose an appropriate repository name and tag.

docker build -t <repository name>:<tag> - < <dockerfile>

Use this command in a Powershell in Windows OS.

Get-Content <dockerfile> | docker build -t <repository name>:<tag> -

6.2 Docker Container

Creating the image via a docker container might be a more familiar way, because you prepare your submission by using a bash terminal for installation of the solver as you may have done for the previous MiniZinc challenges. If you chose this way then we strongly suggest that you record your command in a dockerfile, so that you can create the image from a dockerfile next time and save a lot of time.

1. Create and run a container from the MiniZinc Challenge image by this command. This command also names the container solver.

   docker run -it --name solver minizinc/mznc2020 /bin/bash

   The container should be running now and you should have access to it via the command line. You can test it by the command ls, which should result in the listing of all files and paths in the root directory / of the container.

2. Install your solver as you would normally do in Ubuntu. Modify the files mzn-exec-fd, mzn-exec-free, and mzn-exec-par if needed.

3. Create a docker image from your container solver by running this command. Choose an apriorate repository name and tag.

   docker commit solver <repository name>:<tag>

Note that you can interrupt the installation (Step 2) at anytime by, for example, exiting the bash terminal of the container. On your local machine, use this command for listing all running containers

docker container ls

or this command for all constainers

docker container ls --all

Your container solver should appear in the list. If the container is not running start the container in interactive mode by

docker container start -i solver

If the container is running then access it by

docker exec -it solver /bin/bash

If you want to stop a running container outside from the container use this command.

docker container stop solver

6.3 Testing your Submission

The folder /minizinc in the MiniZinc image contains a very simple MiniZinc model (/minizinc/test.mzn) and one DataZinc file (/minizinc/2.dzn). To test that your solver is correctly setup for the MiniZinc Challenge execute following commands for the search classes you enter.

A successful test should return following output on the screen.

x = 2; ----------

7 Uploading and Solver Submission

You have finalised your solver docker image and have an account on Docker Hub. Following steps need to be performed.

1. You may have to rename your image to match your username at Docker Hub. Use the following command to do so if using the image id

   docker tag <image id> <username>/<target image>:<tag>

   if using the image id of your solver docker image, or

   docker tag <repository>:<tag> <username>/<name>:<tag>

   if using the repository name and tag.

2. Login into your account via command line if not already logged in.

   docker login

3. Push/upload your images to your account.

   docker push <username>/<name>:<tag>

4. If you want to make your repository private then go to Docker Hub, sign in your account, click on your repository, click on settings, and then on the button Make Private.

5. Logout via command line.

   docker logout

6. Send an email to the MiniZinc Challenge Team including
   • the name of your solver,
   • the repository and the tag of your solver submission,
   • an attached file containing the description of your solver,
   • the filled in form Entry Clases, and
   • the filled in form 3rd Party Consent.

8 Docker Cheat Sheet

Docker has an abundance of command-line commands, which are extensively describe in the Online Reference Manual. A short cheat sheet can be found here or a longer one at here. Below is our cheat sheet. Note that <image id> always can be replaced by <repository>:<tag>.