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
+11-10Lines changed: 11 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ Here we are going to create the test beamline repository `t01-services`. When th
22
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.
23
23
24
24
:::{note}
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.
25
+
If you are working in 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.
26
26
:::
27
27
28
28
## To Start
@@ -46,14 +46,15 @@ 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 .`.
@@ -72,11 +73,11 @@ Note the benefits of using copier to create a new repository:
72
73
73
74
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".
74
75
75
-
Now copy the ssh address of your new repository from the GitHub page.
76
+
Now copy the ssh address of your new repository from the GitHub page.
76
77
77
-
:::{figure} ../images/copy_gh_repo_addr.png
78
-
copying the repository address from GitHub
79
-
:::
78
+
:::{figure} ../images/copy_gh_repo_addr.png
79
+
copying the repository address from GitHub
80
+
:::
80
81
81
82
1. Make the first commit and push the repository to GitHub.
82
83
@@ -116,7 +117,7 @@ CalVer is described here: <https://calver.org/> and is used where semantic
116
117
versioning is not appropriate because the repository contains a mix of
117
118
dependencies and does not have a clear API.
118
119
119
-
Note that 2024.9.1 represents the date that this tutorial was last updated.
120
+
Note that 2024.9 represents the date that this tutorial was last updated.
120
121
For completeness you could use the current year and month instead. You
121
122
are also free to choose your own versioning scheme as this is not enforced by
Copy file name to clipboardExpand all lines: docs/tutorials/create_ioc.md
+7-8Lines changed: 7 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Introduction
4
4
5
-
The last section covered deploying and managing the example Instance that came with the template services repository. Here we will create a new IOC Instance that implements a simulated detector.
5
+
The last section covered deploying and managing the example IOC Instance that came with the template services repository. Here we will create a new IOC Instance that implements a simulated detector.
6
6
7
7
For this tutorial some familiarity with the EPICS AreaDetector framework is useful. Take a look at this documentation if you have not yet come across AreaDetector: <https://areadetector.github.io/master/index.html>.
8
8
@@ -38,7 +38,7 @@ code .
38
38
39
39
Our new example IOC will be a simulation detector using the AreaDetector SimDetector. There is already a Generic IOC for the SimDetector, therefore to create an IOC Instance, we just need to refer to that Generic IOC container image and provide some configuration for it.
40
40
41
-
You can find the Generic IOC container source for SimDetector here: <https://github.com/epics-containers/ioc-adsimdetector>. This repository publishes its container image at: `ghcr.io/epics-containers/ioc-adsimdetector-runtime:2024.8.1`. Later tutorials will cover how to build and publish your own Generic IOC container images.
41
+
You can find the Generic IOC container source for SimDetector here: <https://github.com/epics-containers/ioc-adsimdetector>. This repository publishes its container image at: `ghcr.io/epics-containers/ioc-adsimdetector-runtime:2024.8.2`. Later tutorials will cover how to build and publish your own Generic IOC container images.
42
42
43
43
Edit the `compose.yml` file in the `bl01t-ea-cam-01` folder to reflect the new IOC name and to refer to the Generic IOC container image for the SimDetector:
You will need to make a minor change to the `ioc.subst` file. Edit this and remove references to the two template files with `.pvi` in their name. These are PVI generated templates for use with OphydAsync and are not available in manually build IOC Instances.
428
+
You will need to make a minor change to the `ioc.subst` file. Edit this and remove references to the two template files with `.pvi` in their name. These are PVI generated templates for use with OphydAsync and are not available in manually built IOC Instances.
430
429
431
430
Your IOC Instance will now be using the raw startup script and database. But should behave exactly the same as before. You are free to experiment with changes in the startup script and substitution file and re-deploy the IOC.
Copy file name to clipboardExpand all lines: docs/tutorials/deploy_example.md
+21-19Lines changed: 21 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Introduction
4
4
5
-
This tutorial will show you how to deploy and manage the example IOC Instance that came with the template beamline repository. You will need to have your own `t01-services` beamline repository from the previous tutorial.
5
+
This tutorial will show you how to deploy and manage the example IOC Instance `example-test-01`that came with the template beamline repository. You will need to have your own `t01-services` beamline repository from the previous tutorial.
6
6
7
7
For these early tutorials we are not using Kubernetes and instead are deploying IOCs to the local docker or podman instance. These kind of deployments are ideal for testing and development on a developer workstation. They could also potentially be used for production deployments to beamline servers where Kubernetes is not available.
8
8
@@ -31,7 +31,7 @@ If you click on the most recent job you can drill in and see the steps that
31
31
were executed. The most interesting step is `Run IOC checks`. This
32
32
is executing the script `.github/workflows/ci_verify.sh`. This goes through
33
33
each of the IOC Instances in the `services` folder and checks that they
34
-
have valid configuration.
34
+
have a valid configuration.
35
35
36
36
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.
@@ -47,7 +47,7 @@ The standard way to set up your environment for any ec services repository is to
47
47
source ./environment.sh
48
48
```
49
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:-
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
51
- sets permissions on **xhost** to allow local containers to display GUIs on the host.
52
52
- sets **UIDGID** which is used to set which account and group the phoebus container is launched with. This is always 0:0 for podman and USERID:GROUPID for docker. Only required for developer workstations.
53
53
- sets **COMPOSE_PROFILES** which determines which compose profile is launched. Defaults to the 'test' profile intended for testing on developer workstations. It runs a ca-gateway container that publishes PVs on localhost and a container for phoebus to provide an OPI.
@@ -102,25 +102,12 @@ ec ps
102
102
:::{Note}
103
103
Generic IOCs.
104
104
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`.
105
+
You may have noticed that the IOC instance is showing that it has container image `ghcr.io/epics-containers/ioc-template-example-runtime:3.5.1`.
106
106
107
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.
108
108
:::
109
109
110
-
### Monitoring and interacting with an IOC shell
111
-
112
-
To attach to the IOC shell you can use the following command. HOWEVER, this
113
-
will attach you to nothing in the case of this example IOC as it has no
114
-
shell. In the next tutorial we will use this command to interact with
115
-
iocShell.
116
-
117
-
```bash
118
-
ec attach example-test-01
119
-
dbl
120
-
# ctrl-p ctrl-q to detach
121
-
```
122
-
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.
110
+
### Exploring an IOC instance
124
111
125
112
To run a bash shell inside the IOC container:
126
113
@@ -171,7 +158,7 @@ ec stop
171
158
```
172
159
173
160
This will stop all the currently running containers described in the `compose.yml` file.
174
-
However this will leave the resources themselves in place:-
161
+
However this will leave the resources themselves in place:
175
162
- stopped containers
176
163
- container networks
177
164
- container volumes
@@ -181,3 +168,18 @@ To take down the services and remove all of their resources use the following co
181
168
```bash
182
169
ec down
183
170
```
171
+
172
+
### Monitoring and interacting with an IOC shell
173
+
174
+
To attach to the IOC shell you can use the following command. HOWEVER, this
175
+
will attach you to nothing in the case of this example IOC as it has no
176
+
shell. In the next tutorial we will use this command to interact with
177
+
iocShell.
178
+
179
+
```bash
180
+
ec attach example-test-01
181
+
dbl
182
+
# ctrl-p ctrl-q to detach
183
+
```
184
+
185
+
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.
0 commit comments