— This guide applies to Docker for Linux, Docker for macOS and Docker for Windows 10/11 (BUT ONLY in ‘Linux containers’ mode) —

1. Use an already existing Docker image and run a Docker container to compile

• docker pull your_Docker_ID/your_docker_image

start a container in interactive mode: docker run -it your_Docker_ID/your_docker_image

• git clone your_repository
• cd your_folder
• mkdir build; cd build
• cmake …
• make -j 3
• xvfb-run --server-args="-screen 0, 1280x1024x24" ctest -j 3 --output-on-failure
• exit

if needed later, to restart a container in interactive mode: docker start CONTAINER_ID -i (to find CONTAINER_ID: docker ps -a)

2. Create a Docker image

• See this ‘Dockerfile’ sample for inspiration: https://github.com/MEPP-team/MEPP2/blob/master/Docker/Linux/ubuntu-22.04-cgal_5.x.y-pcl_1.1x.y/Dockerfile
• In the folder containing your ‘Dockerfile’:

build the image: docker build -t your_docker_image .

push your Docker image to your personal account on Docker Hub (https://hub.docker.com):

• Log in to the service with ‘docker login’ command
• docker push your_Docker_ID/your_docker_image
• Then sign out with ‘docker logout’ command

3. Enable continuous integration with GitLab

• IMPORTANT: in the web interface of the GitLab repository —> menu on the left ‘Settings’ then ‘CI / CD’ then ‘Auto DevOps’ then uncheck ‘Default to Auto DevOps pipeline’ then ‘Save changes’

3.1. With a ‘Linux Server’ (or a ‘Linux VM’)

WE ARE HERE for Docker but first of all here is an example of continuous integration WITHOUT Docker… ;-) So you can go to the next section directly if you want !

[ USELESS if you already have a dedicated ‘Linux Server’ !

• Install ‘GitLab Runner’: https://docs.gitlab.com/runner/install/linux-repository.html
• ’Register’ your runner(s): https://docs.gitlab.com/runner/register/index.html#linux (it is not compulsory to necessarily use the notion of ‘tags’)

choose ‘shell’ as ‘runner executor’ when asked

USELESS if you already have a dedicated ‘Linux Server’ ! ]

• Add a ‘.gitlab-ci.yml’ to the root of the GitLab repository, here is an example with 2 different configs (same, again, the 2 lines with the ‘n’ tags are optional):

###################
# CONF1 - Release #
###################
#
conf1 - Release:
  tags:
    - my_tag1,my_tag2
  script:
    - mkdir build; cd build
    - cmake .. -DCMAKE_BUILD_TYPE=Release
    - make -j 3
    - xvfb-run --server-args="-screen 0, 1280x1024x24" ctest -j 3 --output-on-failure
    - (...my commands which are good for "myproject"...)

#################
# CONF2 - Debug #
#################
#
conf2 - Debug:
  tags:
    - my_tag1,my_tag2
  script:
    - mkdir build; cd build
    - cmake .. -DCMAKE_BUILD_TYPE=Debug
    - make -j 3
    - xvfb-run --server-args="-screen 0, 1280x1024x24" ctest -j 3 --output-on-failure
    - (...my commands which are good for "myproject"...)

3.2. With Docker

[ USELESS if you already have a dedicated ‘Linux Server’ with Docker !

• Install ‘Docker’: see ‘Docker Install’
• Install ‘GitLab Runner’: https://docs.gitlab.com/runner/install/linux-repository.html
• ’Register’ your runner(s): https://docs.gitlab.com/runner/register/index.html#linux (it is not compulsory to necessarily use the notion of ‘tags’)

choose ‘docker’ as ‘runner executor’ when asked

USELESS if you already have a dedicated ‘Linux Server’ with Docker ! ]

• Add a ‘.gitlab-ci.yml’ to the root of the GitLab repository, here is an example with 2 different configs (one run under Ubuntu 18.04 and one run under Ubuntu 20.04) which show the interest of ‘templates’ (same, again, the 2 lines with the ‘n’ tags are optional):

.linux_build_template_0x - Release: &linux_build_definition_0x-release
  script:
    - mkdir build; cd build
    - cmake .. -DCMAKE_BUILD_TYPE=Release
    - make -j 3
    - xvfb-run --server-args="-screen 0, 1280x1024x24" ctest -j 3 --output-on-failure
    - (...my commands which are good for "myproject"...)

##################
# CONF1 - u18.04 #
##################
#
conf1 - u18.04:
  tags:
    - my_tag1,my_tag2
  image: my_dockerhub_name/my_ubuntu_18.04-for-myproject
  <<: *linux_build_definition_0x-release

##################
# CONF2 - u20.04 #
##################
#
conf2 - u20.04:
  tags:
    - my_tag1,my_tag2
  image: my_dockerhub_name/my_ubuntu_20.04-for-myproject
  <<: *linux_build_definition_0x-release