Instantiate docker containers using custom docker-compose files (sys-admin nomination required)

Prerequisites

Make sure you are registered to the IAM system of INFN-CLOUD, https://iam.cloud.infn.it. Only registered users can login into the INFN-CLOUD dashboard, https://my.cloud.infn.it.

Access to the INFN-CLOUD dashboard enables users to exploit the "docker compose" solution.

User responsibilities

The solution described in this guide consists on instantiation of a Virtual Machine, using the Debian 12 operating system, with docker engine and docker-compose pre-installed, and optionally run a docker compose file fetched from a specified URL. The instantiation of a VM comes with the responsibility of maintaining it and all the services it hosts.

Please read the INFN Cloud AUP in order to understand the responsibilities you have in managing this service.

How to deploy and access services instantiated using docker-compose

Docker-compose allows the instantiation of fully functional production level services by using a set of coordinated dockers. The public IP Address of the VM hosting the docker containers is made available to the docker-compose file as an environment variable: HOST_PUBLIC_IP.

Step 1 - Connecting and authenticating to the INFN-CLOUD dashboard

Connect to the INFN-CLOUD dashboard (https://my.cloud.infn.it/). You can authenticate with the credentials used for the IAM account (https://iam.cloud.infn.it/login) in order to access the dashboard.

Step 2 - Selection of the Deployment type

After login into the dashboard, select the "Docker compose" card in the service catalog and click on the Configure button.

A menu is made available, as in the figure below, and you have to choose the configuration of the docker storage:

The first choice gives the possibility to configure the docker storage on the VM root filesystem, while the second one gives the possibility to attach a volume of a specified size and configure the docker storage to use it. Select the one you are interested in and follow the corresponding sections below, in order to understand what parameters need to be set for each use case.

Select either Automatic or Manual scheduling as shown below:

In the first case, the Orchestrator will take care of choosing the best available provider, in the other case it will be performed a direct submission towards one of the providers available, to be selected from the drop-down menu. In the case of manual scheduling, the flavors displayed on the next page will be those offered by the chosen provider.

Case 1: docker storage on the VM root filesystem

All deployments have a mandatory field Description that needs to be defined before submitting the deployment.

The deployment settings window consists of three tabs:

"General" tab

Here one needs to fill the following required mandatory fields:

• ports: one or more TCP or UDP ports or port ranges can be defined to be open towards the VM running the dockers. They must match the ports that the services inside the docker-compose exposes. Please consult INFN Cloud Rules of participation the "Networking" section in order to see what are the ports that you can specify in this field. If the port you intend to use is in the list of closed-ports, you have to formally request its opening and motivate the request by following the How To: Request to open ports on deployed VMs Also consider that SSH port (22) is already bound to the VM SSH server and thus cannot be used.

• Flavor: resources needed in terms of CPUs and RAM for the new VM.

• Run a docker-compose file: start or not a docker container (Default value is yes).

"Services" tab

• environment_variables: variables to be made available to the docker container at runtime, to be specified on the form of "key:value". Multiple variables can be specified using the "ADD" button.

• docker_compose_file_url: URL from which of the docker compose file to deploy will be downloaded. An example docker-compose file is available here.

• project_name: name of the project. This name will be used to create a folder under /opt to store the docker compose file.

"Advanced" tab

Some advanced parameters can be configured here:

• Creation timeout (minutes): amount of time to wait until the deployment should be considered failed
• Failure policy: delete, or not, the deployment in case of failure
• E-mail: send, or not, a confirmation email when deployment is complete

After configuring all the parameters proceed with "Continue" and then "Submit" your deployment.

Case 2: docker storage on an external volume attached to the VM

If you requested an external volume (2nd option shown in Figure 4), in the "General" tab will be shown an option to select the additional storage size. The external volume will be mounted on the /var/lib/docker instead of the root directory of the VM hosting docker.

Step 3 - Submitting the Docker-compose deployment

After submitting your application, you are redirected to the list of your deployments where you can follow the evolution of the new deployment.

Step 4 - Access your application

On successful completion (CREATE_COMPLETE), you can check your deployment outputs by clicking on the "Details" button and then on the "Output values" Tab.

If the creation of a deployment fails, an additional option (retry) is introduced in the dropdown menu, allowing the user to resubmit the deployment with the same parameters:

If the deletion of a deployment fails, resulting in the status being set to DELETE_FAILED, the "delete (force)" button is displayed in the list of available actions, allowing the user to force the deletion of the deployment:

Use the reported IP address (see figure below) and the ports you defined at submission time to connect to the services you deployed. In order to check the status of the containers use sudo.

In case you used the docker-demo example, that installs a Worpress service with a MaridDB backend, the link to use in order to connect to the frontend is https://wp.<node_ip>.myip.cloud.infn.it where <node_ip> is the value published in the Output details tab.