Setting up a Virtual Machines for firmware implementation#

Warning

Outdated Documentation! This documentation version is out of date. Please check the latest version 2026.1.

To run the Hog CI, you need a dedicated Virtual Machine, since the available shared runners are not ideal to execute heavy software like Vivado or Quartus.

Setting up a dedicated Virtual Machine#

In this section, you can find more information on how to set up your private Gitlab runner. Instructions are provided assuming you have access to the CERN computing resources. If this is not the case, you can still use Hog assuming that you have access to machine running CentOS 7 set up as a Gitlab runner.

In this case, you can ignore the next section and jump directly to [Install Gitlab runner](#install_gitlab runner)

Create a CERN Openstack Virtual Machine#

OpenStack is a cloud operating system that controls large pools of compute, storage, and networking resources through a data-centre, managed and provisioned through APIs with common authentication mechanisms. Openstack provides you with a dashboard from which you can manage VM instances.

More information on Openstack can be found in the Openstack Dashboard Documentation.

To create a new VM, you have to connect to the CERN Openstack dashboard and create a new instance.

Openstack instances come with different flavours, meaning that you can allocate only a fixed amount of each resource to each VM.

Before creating an new instance you can add a new disk that you can use to install the needed tools. To do this go under Volumes -> Volumes on the left navigation bar. Once the Volumes summary appears you can click on + Create Volume and follow the instructions therein. We recommend having at least a 40GB HD

Once you have obtained a custom flavour and a dedicated disk, you can create a new instance. Navigate to Compute > Instances, once you get to the instances summary click on Launch Instance. Fill in the required information in the form that will appear. Under the Source tab select an updated CC7 image: this will generate a VM running under CentOs 7. Select the custom flavour in the Flavor tab. Generate a new key pair and save the private key, this will be needed later to access your VM.

Once a new instance is running (note it might take a few minutes to be generated) attach the Volume you created to the VM. This can be done through the drop down menu on the right side of the instance summary by clicking on attach volume.

You can now connect to your machine through ssh.

NOTE your machine is not fully public yet (reference the Openstack manual for this). This means your VM will be accessible only from the CERN domain. If you are not on the CERN domain, connect to a CERN public machine (lxplus) and then to your machine.

  ssh -i private-key.pem <machine_ip_or_name>

Once you are logged into your machine, change the root password:

  sudo password root

Please follow the IT recommendation when choosing a new password. Mount the volume you created, make sure you own it, format it, etc…

  sudo su                             # become root
  mkfs.ext3 /dev/<diskname>           # format the disk
  mkdir /mnt/vd                       # create mounting point for the disk
  mount /dev/<diskname> /mnt/vd       # mount the disk
  chown -hR <username> /mnt/vd        # own the disk

!!! note “There is no need to add this disk to /etc/fstab for automatic mounting, since Hog will do this automatically”

You are now ready to install your favourite tools!

Installing HDL tools#

You can now install the licensed software (Xilinx Vivado, Mentor Graphics Questasim, …) that you plan to use in your project.

Warning

You are the one responsible for correctly licensing the software

Install Gitlab runner#

Information on how to install a new Gitlab runner on your VM can be found here

Allowing concurrent jobs on a single Openstack Virtual Machine#

  • Log into your VM

  • Open with your preferred editor (with sudo rights) the file /etc/gitlab-runner/config.toml

  • In the global section add concurrent = NUMBER_OF_CONCURRENT_CPU: limits how many jobs globally can be run concurrently. These changes apply to all the runners on the machine independently of the executor [docker, ssh, kubernetes etc]

  • In the runner section add limit = MAX_NUMBER_OF_CONCURRENT_JOB_PER_RUNNER: Limit how many jobs can be handled concurrently by this token. Suppose that we have 2 runners registered by 2 different tokens, then their limits could be adjusted separately : runner-one limit = 3, runner-two limit =5,

  • In the runner section add request_concurrency = NUMBER_OF_CONCURRENT_REQUESTS_PER_NEW_JOBS : Limit number of concurrent requests for new jobs from Gitlab (default 1)

  • Have a look here for more info

  • Example config.toml

  concurrent = 4
  check_interval = 0

  [session_server]
    session_timeout = 1800

  [[runners]]
    limit = 4
    request_concurrency = 4
    name = "Hog vivado runner on mypc"
    url = "https://gitlab.cern.ch"
    token = "ibsaidbasdhubavsuod"
    executor = "shell"
    output_limit = 2000
    [runners.custom_build_dir]
    [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

Hog set-up on the Gitlab runner#

Hog will need the Virtual Machine to be properly set-up as Gitlab runner.

  • clone the Hog VM-setup repository somewhere accessible from the VM, e.g. on you AFS home

  • ssh into your virtual machine as yourself

  • become root (su -u username)

  • export the following system variables:

    • HOG_USERNAME= The name of your service account

    • HOG_VIVADO_DIR= Path of your Vivado SDK installation directory containing the xsetup executable (not required if you run the script with the -x flag)

    • HOG_TOKEN= A valid Gitlab private runner token: Go to Settings -> CI/CD and expand the Runners tab. The registration token in Specific Runners column.

    • HOG_USERGROUP= The name of your user group, e.g. “zp” for ATLAS

  • go to the VM-setup directory and launch the hog-vm-setup.sh script

  • once the script has finished, you can login to the VM as your service account

The new Gitlab runner should now appear in your Gitlab repository, in Settings -> CI/CD -> Runners -> Specific Runners. Remember to enable it for your project.