Create a Beamline Repository

In this tutorial we will create a new ec-services repository.

All IOC Instances that we deploy will be grouped into repositories that define a set of IOC and service instances. Typically each beamline would have its own repository and the accelerator would be split by location or technical area.

In the case of Beamlines, the repo is named after the beamline itself. At DLS we use the naming convention blxxc where xx is the beamline number, and c is the class of beamline.

Note

You may choose your own naming convention, but lower case letters, numbers and hyphens only are recommended for both domain names and IOC names. This is a restriction that helm introduces for package names.

Here we are going to create the test beamline repository bl01t. When the project bl01t is pushed to GitHub, continuous integration (CI) will verify each of the IOC instances.

This beamline repository will be made from a template that comes with a single example IOC and further steps in the following tutorials will teach you how to add your own.

Note

If you are going to work in a shared environment then it is worth choosing a different name for your test beamline and its associated PV prefixes. PVs will be published on the local subnet by default so two people working on the tutorials without doing this will clash. If you do this just remember to substitute your beamline name for bl01t in the following instructions.

To Start

For this exercise you will require a github user account or organization in which to place the new repo. If you do not have one then follow GitHub’s instructions.

Log in to your account by going here login.

You will also need to setup ssh keys to authenticate to github from git. See about ssh.

Create a New Beamline Repo for local deployments

Here we will use the copy the ec services template repository to make a new beamline.

NOTE: for these tutorials we will use your personal GitHub Account to store everything we do, all source repositories and container images. For production, each facility will need its own policy for where to store these assets. See ../explanations/repositories.

Steps

1. Go to your GitHub account home page. Click on ‘Repositories’ and then ‘New’, give your new repository the name bl01t plus a description, then click ‘Create repository’.

2. From a command line with your virtual environment activated. Use copier to start to make a new repository like this:

   pip install copier
   # this will create the folder bl01t in the current directory
   copier copy gh:epics-containers/ec-services-template --trust bl01t
   

3. Answer the copier template questions as follows:

   🎤 Where are you deploying these IOCs and services?
      beamline
   🎤 Short name for the beamline, e.g. "bl47p", "bl20j", "bl21i"
      bl01t
   🎤 A One line description of the module
      beamline bl01t IOC Instances and Services
   🎤 Cluster namespace for these IOCs and services.
      local
   🎤 Git platform hosting the repository.
      github.com
   🎤 The GitHub organisation that will contain this repo.
      YOUR_GITHUB_NAME_GOES_HERE
   🎤 Remote URI of the repository.
      git@github.com:YOUR_GITHUB_NAME/bl01t.git
   

4. Make the first commit and push the repository to GitHub.

   cd bl01t
   git add .
   git commit -m "initial commit"
   git push -u origin main
   

5. Open the project in vscode.

   # DLS users make sure you have done: module load vscode
   code .
   

Wrapping Up

You should now have a working beamline repository. It contains a single IOC Instance which is a very basic example. In the following two tutorials we will investigate the example and then create a real IOC Instance.

You can now give your repository a version tag like this:

# open a terminal in vscode: Menu -> Terminal -> New Terminal
git tag 2024.2.1
git push origin 2024.2.1

We use CalVer version numbers for beamline repositories and Generic IOCs. This is a versioning scheme that uses the date of release as the version number. The last digit is the number of the release in that month.

CalVer is described here: https://calver.org/ and is used where semantic versioning is not appropriate because the repository contains a mix of dependencies and does not have a clear API.

Note that 2024.2.1 represents the time that this tutorial was last updated. For completeness you could use the current year and month instead. You are also free to choose your own versioning scheme as this is not enforced by any of the epics-containers tools.