You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
There are two main kinds of source repositories used in epics-containers:
16
17
17
18
- Generic IOC Source
18
-
- Beamline / Accelerator Domain IOC Instance Source
19
+
- Beamline / Accelerator Services Repositories for IOC instances and other services.
19
20
20
21
### Generic IOC Source Repositories
21
22
22
-
For Generic IOCs it is recommended that these be stored in public repositories
23
-
on GitHub. This allows the community to benefit from the work of others and
24
-
also contribute to the development of the IOC.
23
+
For public Generic IOC container images, the GitHub Container Registry is a good choice. It allows the containers to live at a URL related to the source repository that generated them. The default ioc-template comes with Github Actions that build the container and push it to the GitHub Container Registry.
25
24
26
25
The intention is that a Generic IOC container image is a reusable component
27
26
that can be used by multiple IOC instances in multiple domains. Because
@@ -36,32 +35,24 @@ Integration files for Generic IOCs work with GitHub actions, but also
36
35
can work with DLS's internal GitLab instance (this could be adapted for
37
36
other facilities' internal GitLab instances or alternative CI system).
38
37
39
-
### IOC Instance Domain Repositories
38
+
### IOC Services Repositories
40
39
41
40
These repositories are very much specific to a particular domain or beamline
42
41
in a particular facility. For this reason there is no strong reason to make
43
42
them public, other than to share with others how you are using epics-containers.
44
43
45
-
At DLS we have a private GitLab instance and we store our domain Repositories
44
+
At DLS we have a private GitLab instance and we store our Services Repositories
46
45
there.
47
46
48
47
The CI for domain repos works both with GitHub actions and with DLS's internal
49
48
GitLab instance (this could be adapted for
50
49
other facilities' internal GitLab instances or alternative CI system).
51
50
52
-
### BL45P
51
+
### p45-services
53
52
54
-
The test/example beamline at DLS for epics-containers is BL45P.
55
-
The domain repository for this
56
-
is at <https://github.com/epics-containers/bl45p>. This will always be
57
-
kept in a public repository as it is a live example of a domain repo.
53
+
The test/example beamline at DLS for epics-containers is p45.
54
+
The domain repository for this is at <https://github.com/epics-containers/p45-services>. This will always be kept in a public repository as it is a live example of a domain repo.
58
55
59
-
## Where to put Registries
56
+
This beamline is deployed to Kubernetes at DLS using Argo CD continuous deployment. The repository containing the Argo CD apps that control the deployment is at <https://github.com/epics-containers/p45-deployment>
60
57
61
-
### Generic IOC Container Images and Source Repos
62
58
63
-
Usually GHCR but internal supported for license e.g. Nexus Repository Manager
Copy file name to clipboardExpand all lines: docs/tutorials/create_beamline.md
+42-46Lines changed: 42 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,88 +4,84 @@
4
4
5
5
In this tutorial we will create a new {any}`services-repo`.
6
6
7
-
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.
7
+
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 technical area.
8
8
9
9
In the case of Beamlines, the repo is named after the beamline itself. At DLS
10
-
we use the naming convention `blxxc` where `xx` is the beamline number,
11
-
and c is the class of beamline.
10
+
we use the naming convention `cxx` where `xx` is the beamline number,
11
+
and c is the class of beamline. Our naming convention for beamline services repositories is
12
+
cxx-services.
12
13
13
14
:::{note}
14
15
You may choose your own naming convention, but lower case letters,
15
-
numbers and hyphens only are required for both domain names and
16
+
numbers and hyphens are the only characters allowed for both domain names and
16
17
IOC names. This is a restriction that helm introduces for package names.
17
18
:::
18
19
19
-
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.
20
+
Here we are going to create the test beamline repository `t01-services`. When the project is pushed to GitHub, continuous integration (CI) will verify each of the IOC instances.
20
21
21
22
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.
22
23
23
24
:::{note}
24
-
If you are going to work in a shared environment then it is worth choosing
25
-
a different name for your test beamline and its associated PV prefixes. PVs
26
-
will be published on the local subnet by default so two people working on the
27
-
tutorials without doing this will clash. If you do this just remember to
28
-
substitute your beamline name for `bl01t` in the following instructions.
25
+
If you are working is a shared environment you need not create a unique beamline name or PV prefix because the example runs with all PVs published on localhost only. Your example beamline will be isolated from other users on the same network.
29
26
:::
30
27
31
-
32
28
## To Start
33
29
34
-
For this exercise you will require a github user account or organization in
35
-
which to place the new repo. If you do not have one then follow GitHub's
36
-
[instructions].
30
+
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].
37
31
38
32
Log in to your account by going here <https://github.com/login>.
39
33
40
-
You will also need to set up ssh keys to authenticate to Github from git. See
41
-
[about ssh].
34
+
You will also need to set up ssh keys to authenticate to Github from git. See [about ssh].
42
35
43
36
(create-new-beamline-local)=
44
37
## Create a New Beamline Repo for local deployments
45
38
46
-
Here we will use the ec services template repository to make a new beamline.
39
+
Here we will use a services template repository to make a new beamline.
47
40
48
-
NOTE: for these tutorials we will use your personal GitHub Account to
49
-
store everything we do, all source repositories and container images. For
50
-
production, each facility will need its own policy for where to store these
51
-
assets. See `../explanations/repositories`.
41
+
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 {any}`../explanations/repositories`.
52
42
53
43
## Steps
54
44
55
-
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'.
45
+
1.Make sure you have activated the python virtual environment and that `copier` is installed. See instructions here: {any}`ec`.
56
46
57
-
1.From a command line with your virtual environment activated. Use copier to start to make a new repository like this:
47
+
1.Use copier to copy the services template repository to a new repository named `t01-services`. Note that there are two services templates, one for local deployments (using docker compose) and one for deployments to Kubernetes. We will use the local deployment template here.
58
48
59
-
```bash
60
-
pip install copier
61
-
# this will create the folder bl01t in the current directory
This template will create a new repository for deploying IOCs and services to
58
+
the local machine using docker compose.
59
+
60
+
<fontcolor="#5F87AF">🎤</font><b> Short name for the collection of services, e.g. "t01", "p47", "i20-1", "i21"</b>
61
+
<b> </b><fontcolor="#FFAF00"><b>t01</b></font>
71
62
<fontcolor="#5F87AF">🎤</font><b> A One line description of the module</b>
72
-
<b></b><font color="#FFAF00"><b>beamline bl01t IOC Instances and Services</b></font>
73
-
<font color="#5F87AF">🎤</font><b> Cluster namespace for these IOCs and services.</b>
74
-
<b></b><font color="#FFAF00"><b>local</b></font>
75
-
<font color="#5F87AF">🎤</font><b> Git platform hosting the repository.</b>
<b> </b><fontcolor="#FFAF00"><b>t01 IOC Instances and Services</b></font>
64
+
65
+
Copying from template version 3.5.0
66
+
<fontcolor="#06989A"> ... </font>
81
67
</pre>
82
68
69
+
1. Create your new repository on GitHub in your personal space by following this link <https://github.com/new>. Give it the name t01-services and a description of "t01 IOC Instances and Services". Then click "Create repository".
70
+
71
+
Now copy the ssh address of your new repository from the GitHub page.
72
+
73
+
:::{figure} ../images/copy_gh_repo_addr.png
74
+
copying the repository address from GitHub
75
+
:::
76
+
83
77
1. Make the first commit and push the repository to GitHub.
84
78
85
79
```bash
86
-
cd bl01t
80
+
cd t01-services
81
+
git init -b main
87
82
git add .
88
83
git commit -m "initial commit"
84
+
git remote add origin >>>>paste your ssh address here<<<<
89
85
git push -u origin main
90
86
```
91
87
@@ -104,8 +100,8 @@ You can now give your repository a version tag like this:
104
100
105
101
```bash
106
102
# open a terminal in vscode: Menu -> Terminal -> New Terminal
107
-
git tag 2024.3.1
108
-
git push origin 2024.3.1
103
+
git tag 2024.9.1
104
+
git push origin 2024.9.1
109
105
```
110
106
111
107
We use `CalVer` version numbers for beamline repositories and Generic IOCs.
@@ -116,7 +112,7 @@ CalVer is described here: <https://calver.org/> and is used where semantic
116
112
versioning is not appropriate because the repository contains a mix of
117
113
dependencies and does not have a clear API.
118
114
119
-
Note that 2024.3.1 represents the time that this tutorial was last updated.
115
+
Note that 2024.9.1 represents the date that this tutorial was last updated.
120
116
For completeness you could use the current year and month instead. You
121
117
are also free to choose your own versioning scheme as this is not enforced by
Copy file name to clipboardExpand all lines: docs/tutorials/setup_workstation.md
+11-1Lines changed: 11 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -80,7 +80,17 @@ The links below have details of how to install your choice of container platform
80
80
-[Install docker]
81
81
-[Install podman]
82
82
83
-
The docker install page encourages you to install Docker Desktop. This is a paid for product and is not required for this tutorial. You can install the free linux CLI tools by clicking on the appropriate linux distribution link.
83
+
The docker install page encourages you to install Docker Desktop. This is a paid for product and is not required for this tutorial. You can install the free linux CLI tools by clicking on the appropriate linux distribution link under the "Supported Platforms" heading, for simplicity it is easiest to use the option "Install using the convenience script".
84
+
85
+
### docker compose for podman users
86
+
docker compose allows you to define and run multi-container Docker applications. epics-containers uses it for describing a set of IOCs and other serial services that are deployed together.
87
+
88
+
If you installed docker using the above instructions then docker compose is already installed. If you installed podman then you will need to install docker compose separately. We prefer to use docker-compose instead of podman-compose because it is more widely and avoids behaviour differences between the two tools. If you are at DLS you just need to run 'module load docker-compose' to get access to docker compose with podman as the back end.
89
+
90
+
Other users of podman please see these instructions [rootless podman with docker-compose](https://connect.redhat.com/hydra/prm/v1/business/companies/0ed5e6899bce415b89d82cb334da214a/linked-resources/aa9ae6ada5f04000a66472cc0fc18160/content/public/view)
0 commit comments