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
Copy file name to clipboardExpand all lines: docs/tutorials/create_beamline.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,6 +46,10 @@ NOTE: for these tutorials we will use your personal GitHub Account to store ever
46
46
47
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.
48
48
49
+
Note the benefits of using copier to create a new repository:
50
+
- you can template the repository and use questions to fill in the template, making a unique result.
51
+
- if the template changes in future you can merge the changes into you repository without losing your changes, simply by running `copier update .`.
For the moment just check that your CI passed and if not review that you
37
37
have followed the instructions in the previous tutorial correctly.
38
38
39
-
(setup-beamline-bl01t)=
39
+
(setup-beamline-t01)=
40
40
## Set up Environment for the t01 Beamline
41
41
42
-
It is much easier to investigate the commands available to you with command line completion enabled. You need only do the following steps once to permanently enable this feature.
42
+
Make sure you have a terminal open and the current working directory is your `t01-services` project root folder.
43
43
44
-
```bash
45
-
# these steps will make cli completion work for bash
The standard way to set up your environment for any ec services repository is to get the environment.sh script from the domain repository and source it.
55
-
56
-
Start this section of the tutorial inside the vscode project that you created in the previous tutorial. Make sure you have a terminal open and the current working directory is your `bl01t` project root folder.
57
-
58
-
First make sure you have the local binaries folder in your path by adding
59
-
the following to the end of your `$HOME/.bash_profile` file:
44
+
The standard way to set up your environment for any ec services repository is to source the environment.sh script from the root of the services repo. i.e.
60
45
61
46
```bash
62
47
source ./environment.sh
63
48
```
64
49
50
+
The environment file is the same for all local deployment services projects and sets up the following. The defaults supplied are all intended for developer workstation use:-
51
+
52
+
-**UIDGID** Used to set which account and group containers are launched with. This is always 0:0 for podman and USERID:GROUPID for docker. Only required for developer workstations.
53
+
-**COMPOSE_PROFILES** Determines which compose profile is launched. Defaults to the 'develop' profile intended for developer workstations. It runs a ca-gateway container that publishes PVs on localhost and a container for phoebus to provide an OPI.
54
+
-**EPICS_CA_ADDR_LIST** Set to localhost so that host caget's can see the containerised IOC PVs on a developer workstation.
55
+
65
56
66
57
(deploy-example-instance)=
67
58
## Deploy the Example IOC Instance
68
59
69
-
For this section we will be making use of the epics-containers-cli tool.
70
-
This command line entry point for the tool is `ec`. For more
71
-
details see: {any}`CLI` or try `ec --help`.
72
-
73
-
The simplest command to check that the tool is working is `ps` which lists
74
-
the IOC Instances that are currently running:
60
+
To launch all the services described by the `compose.yml` file in the root of the services repository, make sure your current working directory is still the root of your your `t01-services` project and run the following command:
75
61
76
62
```bash
77
-
ec ps
63
+
docker compose up -d
78
64
```
79
65
80
-
You should see no IOCs listed as you have not yet started an IOC Instance.
81
-
82
-
The following command will deploy the example IOC instance to your local
83
-
machine (unless you have skipped ahead and set up your Kubernetes config
84
-
in which case the same command will deploy to your Kubernetes cluster).
85
-
86
-
```bash
87
-
cd bl01t # (if you are not already in your beamline repo)
88
-
ec deploy-local services/bl01t-ea-test-01
89
-
```
66
+
The `up` command tells compose to make sure all of the services are up and running. The `-d` flag tells compose to detach and run the services in the background. If you don't specify -d then your terminal will attach to the stdout of the services and you will see their output as they start up. This can be useful and is done with colour coding so you can distinguish between the different services (terminal colours must be enabled).
90
67
91
-
You will be prompted to say that this is a *TEMPORARY* deployment. This is
92
-
because we are deploying directly from the local filesystem. You should only
93
-
use this for testing purposes because there is no guarantee that you could
94
-
ever roll back to this version of the IOC (as it is lost as soon as filesystem
95
-
changes are made). Local filesystem deployments are given a beta version
96
-
number to indicate that they are not permanent.
97
-
98
-
You can now see the beta IOC instance running with:
99
-
100
-
<pre>$ ec ps
101
-
| name | version | running | restarts | deployed |
At the end of the last tutorial we tagged the beamline repository with a
106
-
`CalVer` version number and pushed it up to GitHub. This means that we
107
-
can now use that tagged release of the IOC instance. First let's
108
-
check that the IOC instance version is available as expected. The following
109
-
command lists all of the tagged versions of the IOC instance that are
110
-
available in the GitHub repository.
111
-
112
-
<pre>$ ec instances bl01t-ea-test-01
113
-
| version |
114
-
|----------|
115
-
| 2024.3.1 |
116
-
</pre>
117
-
118
-
:::{note}
119
-
The above command is the first one to look at your github repository.
120
-
This is how it finds out the versions
121
-
of the IOC instance that are available. If you get an error it may be
122
-
because you set EC_SERVICES_REPO incorrectly in environment.sh. Check it
123
-
and source it again to pick up any changes.
124
-
:::
68
+
There will be a short delay the first time while the container images are downloaded from the GitHub container registry to your local image cache. Subsequent runs will be much faster.
125
69
126
-
:::{hint}
127
-
ec supports command line completion, which means that entering `<tab> <tab>` will give hints on the command line:
Be aware of the distinction of `deploy-local` vs `deploy`. Both of these commands create a running instance of the IOC in the target environment (currently your local machine - later on a Kubernetes Cluster). However, `deploy-local` gets the IOC instance description YAML direct from your local filesystem. This means it is not likely to be available for re-deployment later on. `deploy` gets the IOC instance description YAML from the GitHub repository with a specific tag and therefore is a known state that can be recovered at a later date.
157
-
158
-
Always strive to have released versions of IOC instances deployed in your
159
-
environments. `deploy-local` is only for temporary testing purposes.
83
+
In environment.sh we created an alias for `docker compose` named `ec` from now on we'll shorten the commands to use `ec` instead of `docker compose`.
160
84
161
85
## Managing the Example IOC Instance
162
86
163
87
### Starting and Stopping IOCs
164
88
165
-
To stop / start the example IOC try the following commands. Note that
166
-
`ec ps -a` shows you all IOCs including stopped ones.
89
+
To stop / start the example IOC try the following commands. Note that `ec ps -a` shows you all IOCs including stopped ones.
90
+
91
+
Also note that tab completion should allow you to complete the names of your commands and services. e.g.
92
+
`ec star <tab> ex <tab>`, should complete to `ec start example-test-01`.
167
93
168
94
```bash
169
95
ec ps -a
170
-
ec stop bl01t-ea-test-01
96
+
ec stop example-test-01
171
97
ec ps -a
172
-
ec start bl01t-ea-test-01
98
+
ec start example-test-01
173
99
ec ps
174
100
```
175
101
176
102
:::{Note}
177
103
Generic IOCs.
178
104
179
-
You may have noticed that the IOC instance has is showing that it has
180
-
an image `ghcr.io/epics-containers/ioc-adsimdetectorruntime:2024.4.1`.
105
+
You may have noticed that the IOC instance has is showing that it has container image `ghcr.io/epics-containers/ioc-template-example-runtime:3.5.1`.
181
106
182
-
This is a Generic IOC image and all IOC Instances must be based upon one
183
-
of these images. This IOC instance has no startup script and is therefore
184
-
not functional, it could have been based on any Generic IOC.
107
+
This is a Generic IOC image and all IOC Instances must be based upon one of these images. ioc-template-example-runtime is an instantiation of the template project for creating new Generic IOCs. It has only deviocstats support and no other support modules. This generic IOC can be used for serving records out of a database file as we have done in this example.
185
108
:::
186
109
187
110
### Monitoring and interacting with an IOC shell
@@ -192,59 +115,49 @@ shell. In the next tutorial we will use this command to interact with
192
115
iocShell.
193
116
194
117
```bash
195
-
ec attach bl01t-ea-test-01
118
+
ec attach example-test-01
119
+
dbl
120
+
# ctrl-p ctrl-q to detach
196
121
```
197
122
198
-
Use the command sequence ctrl-P then ctrl-Q to detach from the IOC. **However,
199
-
there are issues with both VSCode and IOC shells capturing ctrl-P. until
200
-
this is resolved it may be necessary to close the terminal window to detach.**
201
-
You can also restart and detach from the IOC using ctrl-D or ctrl-C, or
202
-
by typing `exit`.
123
+
Use the command sequence ctrl-P then ctrl-Q to detach from the IOC. **However, there are issues with both VSCode and IOC shells capturing ctrl-P**. Until this is resolved it may be necessary to close the terminal window to detach. You can also restart and detach from the IOC using ctrl-D or ctrl-C, or by typing `exit`. If you do this docker will restart your IOC right away.
203
124
204
125
To run a bash shell inside the IOC container:
205
126
206
127
```bash
207
-
ec exec bl01t-ea-test-01
128
+
ec exec example-test-01 bash
129
+
caget EXAMPLE:SUM
208
130
```
209
131
210
-
Once you have a shell inside the container you could inspect the following
211
-
folders:
132
+
Once you have a shell inside the container you could inspect the following folders. Because this is the runtime container you will only see the binaries and runtime files, not the source code:
/epics/ioc/config IOC instance config used to generate runtime files
141
+
/epics/runtime IOC startup script and database file generated at runtime
142
+
================== ===================
221
143
```
222
144
223
-
Being at a terminal prompt inside the IOC container can be useful for debugging
224
-
and testing. You will have access to caget and caput, plus other EPICS tools,
225
-
and you can inspect files such as the IOC startup script.
145
+
Being at a terminal prompt inside the IOC container can be useful for debugging and testing. You will have access EPICS command line tools including pvAccess, and you can inspect files such as the IOC startup script.
146
+
147
+
In the Virtual Machine supplied for testing epics-containers we do not install EPICS into the host environment. Instead you can use an IOC container when you need EPICS tools. Working this way makes your developer environment very portable, you only require docker or podman to work on any IOC project. It is equally possible to install EPICS on your host and use the host tools to interact with the IOC container, for the developer configuration you would just need to make sure `EPICS_CA_ADDR_LIST=127.0.0.1`.
226
148
227
149
### Logging
228
150
229
151
To get the current logs for the example IOC:
230
152
231
153
```bash
232
-
ec logs bl01t-ea-test-01
154
+
ec logs example-test-01
233
155
```
234
156
235
157
Or follow the IOC log until you hit ctrl-C:
236
158
237
159
```bash
238
-
ec logs bl01t-ea-test-01 -f
239
-
```
240
-
241
-
You should see the log of ibek loading and generating the IOC startup assets and then the ioc shell startup script log.
242
-
243
-
You can also attach to the IOC and check that it has started correctly by using the 'dbl' command to list all the records in it's IOC database.
244
-
245
-
```bash
246
-
ec attach bl01t-ea-test-01
247
-
dbl
248
-
# ctrl-p ctrl-q to detach
160
+
ec logs example-test-01 -f
249
161
```
250
162
163
+
You should see the log of ibek loading and generating the IOC startup assets and then the ioc shell startup script log. Ibek is the tool that runs inside of the IOC container and generates the ioc shell script and database file by interpreting the /epics/ioc/config/ioc.yaml at launch time.
Copy file name to clipboardExpand all lines: docs/tutorials/ioc_changes1.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -89,7 +89,7 @@ git push origin 2024.3.2
89
89
ec deploy bl01t-ea-test-02 2024.3.2
90
90
```
91
91
92
-
NOTE: the above assumes you have an active python virtual environment with the `edge-containers-cli` installed and you have sourced the beamline environment file (for a reminder of how to do this see {any}`setup-beamline-bl01t`).
92
+
NOTE: the above assumes you have an active python virtual environment with the `edge-containers-cli` installed and you have sourced the beamline environment file (for a reminder of how to do this see {any}`setup-beamline-t01`).
93
93
94
94
You can now see that the versioned IOC instance is running and loading the extra.db by looking at its log with:
Copy file name to clipboardExpand all lines: docs/tutorials/setup_workstation.md
+23-4Lines changed: 23 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,11 +82,11 @@ The docker install page encourages you to install Docker Desktop. This is a paid
82
82
83
83
### Docker Compose For Podman Users
84
84
85
-
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.
85
+
docker compose allows you to define and run multi-container Docker applications. epics-containers uses it for describing a set of IOCs and other services that are deployed together.
86
86
87
87
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 used 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.
88
88
89
-
Other users of podman please see these instructions [rootless docker with docker-compose](https://connect.redhat.com/hydra/prm/v1/business/companies/0ed5e6899bce415b89d82cb334da214a/linked-resources/aa9ae6ada5f04000a66472cc0fc18160/content/public/view).
89
+
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).
90
90
91
91
### Important Notes Regarding docker and podman
92
92
@@ -99,8 +99,27 @@ in your `.bashrc` file.
99
99
`docker` users should also take a look at this page: [](../reference/docker.md) which describes a couple of extra steps that are required to make docker work in developer containers.
100
100
101
101
102
-
(python-setup)=
102
+
### Command Line Completion
103
+
104
+
This is an optional step to set up CLI completion for docker or podman.
103
105
106
+
It is much easier to investigate the commands available to you with command line completion enabled. You need only do the following steps once to permanently enable this feature for docker and docker compose.
107
+
108
+
```bash
109
+
# these steps will make cli completion work for bash
0 commit comments