How To: 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 responsabilities

Important

The solution described in this guide consists on instantiation of a Virtual Machine, using Ubuntu 20.04 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 responsabilities 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.

Fig 1: INFN-CLOUD welcome dashboard

Fig 1: INFN-CLOUD welcome dashboard

INFN-CLOUD IAM login

Fig2: INFN-CLOUD IAM login

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.

dashboard

Fig3: Dashboard

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

General Tab

Fig4: General Tab

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 storege 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.

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.

VM configuration parameters

Fig5: VM configuration parameters

The deployment settings window consists of three tabs:

“General” TAB

Here one need 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 expose.

Important

INFN Cloud has a clearly defined list of open ports (see_reference in the Networking section). The opening of any port that is not present in the above mentioned list must be formally requested through the INFN Cloud ServiceDesk.

List of ports

Fig6: List of ports

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

Fig7: Flavor selection.

  • docker_storage_size: storage size of the root filesystem.
Additional storage definition

Fig13: Additional storage definition

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

Fig8: Run or not the containers

“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.
environment variables definition

Fig9: environment variables definition

  • 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.
Docker-compose file URL

Fig10: Docker-compose file URL

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

Fig11: project name

“Advanced” TAB

Some advanced parameters can be configured here:

  • Scheduling: set automatic (recommended) or manual (perform a direct submission towards one of the providers available) scheduling
  • 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
Advanced Tab

Fig12: Advanced Tab

After configuring all the parameters proceed with the “Submit” as described in the “Step 3 - Submitting the Docker-compose deployment”.

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

The only difference from the previous case is that the volume created with a size equal to the parameter “docker_storage_size” will be mounted on the /var/lib/docker instead of the root directory of the VM hosting docker.

external storage definition

Fig13: external storage definition

Step 3 - Submitting the Docker-compose deployment

After submitting your application (“Submit” green button), you are redirected to the list of your deployments where you can follow the evolution of the new deployment.

Step 3

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.

Step 4

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”.

Check output details

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.