Skip to content

Commit facee39

Browse files
gilesknapgilesknap
authored
Merge pull request #34 from epics-containers/dev
Fixes from First Review
2 parents 56957ca + a133776 commit facee39

File tree

10 files changed

+78
-130
lines changed

10 files changed

+78
-130
lines changed

‎docs/user/how-to/run_iocs.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ thing as the above podman command:
4848

4949
.. code-block:: bash
5050
51-
ec dev ioc-launch iocs/bl01t-ea-ioc-01 --tag 23.3.3
51+
ec dev ioc-launch iocs/bl01t-ea-ioc-01
5252
5353
That is because ``ioc-launch`` is intended for locally testing an IOC instance
5454
that is destined for Kubernetes.

‎docs/user/reference/cli.rst

Lines changed: 0 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -19,103 +19,3 @@ or by setting the ``K8S_QUIET=true`` in your environment.
1919
The CLI entrypoint is ``ec``. To see the available commands, run ``ec --help``.
2020
Much of the functionality is available through subcommands dev and ioc.
2121
Below is pasted the current version of help for the CLI.
22-
23-
.. code-block::
24-
25-
26-
[E7][work-ec]$ ec --help
27-
28-
Usage: ec [OPTIONS] COMMAND [ARGS]...
29-
30-
EPICS Containers assistant CLI
31-
32-
╭─ Options ─────────────────────────────────────────────────────╮
33-
│ --version Log the version of ec and │
34-
│ exit │
35-
│ --domain -d TEXT Domain namespace to use │
36-
│ [default: bl01t] │
37-
│ --image-registry TEXT Image registry to pull │
38-
│ from │
39-
│ [default: │
40-
│ ghcr.io/gilesknap] │
41-
│ --helm-registry TEXT Helm registry to pull │
42-
│ from │
43-
│ [default: │
44-
│ ghcr.io/gilesknap] │
45-
│ --quiet -q Suppress printing of │
46-
│ commands executed │
47-
│ --log-level TEXT Log level (DEBUG, INFO, │
48-
│ WARNING, ERROR, CRITICAL) │
49-
│ [default: WARN] │
50-
│ --install-completion Install completion for │
51-
│ the current shell. │
52-
│ --show-completion Show completion for the │
53-
│ current shell, to copy it │
54-
│ or customize the │
55-
│ installation. │
56-
│ --help Show this message and │
57-
│ exit. │
58-
╰───────────────────────────────────────────────────────────────╯
59-
╭─ Commands ────────────────────────────────────────────────────╮
60-
│ dev Commands for building, debugging containers. See │
61-
│ 'ec dev --help' │
62-
│ ioc Commands for managing IOCs in the cluster. See 'ec │
63-
│ ioc --help' │
64-
│ monitor Monitor the status of IOCs in a domain │
65-
│ ps List the IOCs running in the current domain │
66-
│ resources Output information about a domain's cluster │
67-
│ resources │
68-
╰───────────────────────────────────────────────────────────────╯
69-
70-
[E7][work-ec]$ ec dev --help
71-
72-
Usage: ec dev [OPTIONS] COMMAND [ARGS]...
73-
74-
Commands for building, debugging containers. See 'ec dev
75-
--help'
76-
77-
╭─ Options ─────────────────────────────────────────────────────╮
78-
│ --help Show this message and exit. │
79-
╰───────────────────────────────────────────────────────────────╯
80-
╭─ Commands ────────────────────────────────────────────────────╮
81-
│ build Build a container locally from a container │
82-
│ project. │
83-
│ debug-last Launches a container with the most recent image │
84-
│ build. Useful for debugging failed builds │
85-
│ ioc-launch Launch an IOC instance using a local helm chart │
86-
│ definition. Set folder for a locally editable │
87-
│ generic IOC or tag to choose any version from the │
88-
│ registry. │
89-
│ launch Launch a bash prompt in a container │
90-
│ make make the generic IOC source code inside its │
91-
│ container │
92-
╰───────────────────────────────────────────────────────────────╯
93-
94-
[E7][work-ec]$ ec ioc --help
95-
96-
Usage: ec ioc [OPTIONS] COMMAND [ARGS]...
97-
98-
Commands for managing IOCs in the cluster. See 'ec ioc --help'
99-
100-
╭─ Options ─────────────────────────────────────────────────────╮
101-
│ --help Show this message and exit. │
102-
╰───────────────────────────────────────────────────────────────╯
103-
╭─ Commands ────────────────────────────────────────────────────╮
104-
│ attach Attach to the IOC shell of a live IOC │
105-
│ delete Remove an IOC helm deployment from the cluster │
106-
│ deploy Pull an IOC helm chart and deploy it to the │
107-
│ cluster │
108-
│ deploy-local Deploy a local IOC helm chart directly to the │
109-
│ cluster with dated beta version │
110-
│ exec Execute a bash prompt in a live IOC's container │
111-
│ log-history Open historical logs for an IOC │
112-
│ logs Show logs for current and previous instances of │
113-
│ an IOC │
114-
│ restart Restart an IOC │
115-
│ start Start an IOC │
116-
│ stop Stop an IOC │
117-
│ template print out the helm template generated from a │
118-
│ local ioc helm chart │
119-
│ versions List all versions of the IOC available in the │
120-
│ helm registry │
121-
╰───────────────────────────────────────────────────────────────╯

‎docs/user/tutorials/create_beamline.rst

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ template repo, so that you can easily pull in changes from the template
7373
repo in the future.
7474

7575
#. Create a new, completely blank repository in your GitHub account
76-
called ``bl01t``. To do this got to https://github.com/new
76+
called ``bl01t``. To do this go to https://github.com/new
7777
and fill in the details as per the image below. Click
7878
``Create repository``.
7979

@@ -87,16 +87,19 @@ repo in the future.
8787
mv iocs/blxxi-ea-ioc-01/ iocs/bl01t-ea-ioc-01
8888
mv opi/blxxi-ea-ioc-01/ opi/bl01t-ea-ioc-01
8989
# careful to use find *, NOT find . or you will change the .git folder
90-
sed -i 's/BLXXI/BL01T/g' $(find * -type f)
91-
sed -i 's/blxxi/bl01t/g' $(find * -type f)
90+
sed -i s/blxxi/bl01t/g $(find * -type f)
91+
# use your username as the prefix to all PV names
92+
# this ensures multiple simultaneous users do not clash
93+
sed -i s/BLXXI/$USER/g $(find * -type f)
9294
9395
.. note::
9496

9597
If you are sharing the bl01t namespace on a cluster with other users
96-
(e.g. if you are at DLS) then consider changing the name of your IOC
98+
(e.g. if you are at **DLS**) then change the name of your IOC
9799
to something unique. To do this rename the folder iocs/bl01t-ea-ioc-01
98100
to your unique name and edit the ``name:`` field at the top of
99-
``Chart.yaml`` to match the folder name.
101+
``Chart.yaml`` to match the folder name. The suggested name is your
102+
username as the prefix e.g. hgv27681-ea-ioc-01.
100103

101104
If you do this - remember to substitute in your own name in the
102105
following steps, replacing bl01t-ea-ioc-01.
@@ -115,7 +118,15 @@ repo in the future.
115118
git remote add origin [email protected]:<YOUR USER NAME>/bl01t.git
116119
git add .
117120
git commit -m "rename blxxi to bl01t"
118-
git push origin main
121+
git push --set-upstream origin main
122+
123+
As this is your first commit you may find that you need to set your
124+
username and email address for git. If so, follow the instructions
125+
that git gives you. In theory this should be handled for you by
126+
vscode devcontainers but this does not always work.
127+
See `git in vscode`_.
128+
129+
.. _git in vscode: https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials
119130

120131
.. figure:: ../images/create_repo.png
121132

@@ -141,6 +152,7 @@ The example version below was the first revision in the month of April 2023.
141152
142153
cd bl01t
143154
git tag 23.4.1
155+
# push the tag
144156
git push origin 23.4.1
145157
146158
This will cause GitHub to create a release of the project and trigger

‎docs/user/tutorials/debug_generic_ioc.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,4 +231,4 @@ the image to a container registry so that it can run in Kubernetes.
231231

232232

233233
.. Once running:-
234-
.. caput -S BL01T-EA-TST-02:CAM:URL1
234+
.. caput -S $USER-EA-TST-02:CAM:URL1

‎docs/user/tutorials/deploy_example.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,9 @@ IOC Instance.
3636
point. For more information see `CLI` or try ``ec --help``.
3737

3838

39-
The following command will deploy the example IOC instance to your cluster:
39+
The following command will deploy the example IOC instance to your cluster
40+
(if you changed the ioc name in the previous tutorial then
41+
remember to change bl01t-ea-ioc-01 to your unique name here):
4042

4143
.. code-block:: bash
4244
@@ -61,7 +63,9 @@ monitor the progress (hit ctrl-C to stop following the logs):
6163
ec ioc logs bl01t-ea-ioc-01 -f
6264
6365
Note there may be a little delay while the cluster pulls the generic IOC
64-
image from the GitHub container registry.
66+
image from the GitHub container registry. The error
67+
"recGblRecordError: devStringinEnvVar (init_record) Illegal INP parm field Illegal field value PV: BL01T-EA-IOC-01:TIMEZONE"
68+
is benign, TODO: take a look at the cause of this error.
6569

6670
Once the IOC is running you can find out the IP address of the pod it is
6771
running in with:
@@ -91,7 +95,7 @@ You can now launch the client applications as follows:
9195
.. code-block:: bash
9296
9397
./blxxi-ea-ioc-01-gui.sh
94-
c2dv --pv BL01T-EA-TST-01:IMAGE
98+
c2dv --pv $USER-EA-TST-01:IMAGE
9599
96100
Now make sure the AreaDetector is Acquiring by clicking Start if needed on
97101
the CAM screen. Next click on Auto to scale the

‎docs/user/tutorials/devcontainer.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ epics devcontainer tutorial.
1515
Configure Visual Studio Code
1616
----------------------------
1717

18-
You must ensure you have the devcontainer plugin:
18+
You must ensure you have the devcontainer plugin. This is installed as part
19+
of `Remote Development`_ in the previous tutorial:
1920

2021

2122
.. figure:: ../images/dev-container-plugin.png
@@ -24,6 +25,7 @@ You must ensure you have the devcontainer plugin:
2425

2526
devcontainer plugin
2627

28+
.. _Remote Development: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack
2729

2830
For podman users, you must first tell VSCode to use podman instead of docker.
2931
Open a VSCode window and hit "ctrl ," (control-comma) to open the user

‎docs/user/tutorials/epics_devcontainer.rst

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -82,12 +82,8 @@ Configuring the Devcontainer
8282
configured for interacting with the test beamline bl01t on the test
8383
cluster Pollux. HOWEVER: for this exercise we will use your personal
8484
GitHub account to avoid clashes with other users of this tutorial.
85-
Therefore follow the instructions below and set KUBECONFIG as follows:
86-
87-
.. code-block:: bash
88-
89-
# point at your cluster configuration file
90-
export KUBECONFIG=/home/${USER}/.kube/config_pollux
85+
Therefore the ``K8S_HELM_REGISTRY`` variable must be set to your
86+
GitHub user name and the other variables left as is.
9187

9288
To enable access to the pollux cluster, execute the following commands
9389
from OUTSIDE of the dev container:

‎docs/user/tutorials/ioc_changes.rst

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,12 @@ is working.
5151
Make the following changes in your test IOC config folder
5252
(``bl01t/iocs/bl01t-ea-ioc-01/config``):
5353

54-
1. Add a file called ``extra.db`` with the following contents:
54+
1. Add a file called ``extra.db`` with the following contents.
55+
IMPORTANT replace [$USER] with your username:
5556

5657
.. code-block:: text
5758
58-
record(ai, "BL01T-EA-IOC-01:TEST") {
59+
record(ai, "[$USER]-EA-IOC-01:TEST") {
5960
field(DESC, "Test record")
6061
field(DTYP, "Soft Channel")
6162
field(SCAN, "Passive")
@@ -78,23 +79,40 @@ folder:
7879

7980
.. code-block:: bash
8081
81-
ec dev ioc-launch iocs/bl01t-ea-ioc-01 --tag 23.3.4
82+
ec dev ioc-launch iocs/bl01t-ea-ioc-01
8283
83-
The ``--tag`` option specifies the version of the Generic IOC container to use
84-
and this means it will be pulled from the container registry (or come from
85-
the cache if it has already been pulled).
86-
If you do not supply a tag then ``ec`` will look for a local copy of the
87-
container to use, we will cover this in `generic_ioc`.
84+
This will launch Generic IOC container specified in the ``bl01t-ea-ioc-01``
85+
helm chart and mount into it the local config specified in
86+
``/iocs/bl01t-ea-ioc-01/config``.
8887

8988
If all is well you should see your iocShell prompt and you can test your change
9089
from another terminal (VSCode menus -> Terminal -> New Terminal) like so:
9190

9291
.. code-block:: bash
9392
94-
caget BL01T-EA-IOC-01:TEST
93+
caget $USER-EA-IOC-01:TEST
9594
9695
If you see the value 1 then your change is working.
9796

97+
.. note::
98+
99+
If you also wanted to make local changes
100+
to the generic IOC itself you could clone the generic IOC source repo,
101+
locally build the container image and then use ``ec dev ioc-launch`` as
102+
follows:
103+
104+
.. code-block:: bash
105+
106+
# advanced example - not part of this tutorial
107+
cd <root of your workspace>
108+
git clone [email protected]:epics-containers/ioc-adsimdetector.git
109+
cd ioc-adsimdetector
110+
# this makes a local image with tag :local
111+
ec dev build
112+
cd ../bl01t
113+
ec dev ioc-launch iocs/bl01t-ea-ioc-01 ../ioc-adsimdetector
114+
115+
98116
Note you can see your running IOC in podman using this command:
99117

100118
.. code-block:: bash
@@ -156,7 +174,7 @@ from the above command):
156174
.. code-block:: bash
157175
158176
export EPICS_CA_ADDR_LIST=192.168.0.32
159-
caget BL01T-EA-IOC-01:TEST
177+
caget $USER-EA-IOC-01:TEST
160178
161179
Once you are happy with your changes you can push and tag your beamline repo.
162180
This will publish a new version of the IOC instance helm chart to the OCI helm

‎docs/user/tutorials/rtems_ioc.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,16 @@ runs, it deploys a kubernetes pod that manages the RTEMS IOC. It does contain
229229
the IOC's configuration and the IOC's binary code, which it will copy to the
230230
file-server on startup.
231231

232+
Finally you will need to tell the IOC to mount the Persistent Volume Claim
233+
that the bl01t-ioc-files service is serving over NFS and TFTP. To do this
234+
add the following lines to ``iocs/bl01t-ea-ioc-02/values.yaml``:
235+
236+
.. code-block:: yaml
237+
238+
# for RTEMS IOCS this is the PVC name for the filesystem where RTEMS
239+
# IOCs look for their files - enable this in RTEMS IOCs only
240+
nfsv2TftpClaim: bl01t-ioc-files-claim
241+
232242
You are now ready to deploy the IOC instance to the cluster and test it out.
233243

234244

‎docs/user/tutorials/setup_workstation.rst

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,12 +55,18 @@ First download and install Visual Studio Code.
5555
- `Download Visual Studio Code`_
5656
- `Setup Visual Studio Code`_
5757

58-
Add the following extensions to Visual Studio Code:
58+
VSCode has an huge library of extensions. The following list of extensions are
59+
useful for working with epics-containers. You will need to install the *Required*
60+
extensions before proceeding to the next tutorial. See the links for instructions
61+
on how to do this.
62+
63+
The recommended extensions will be installed for you when you launch the
64+
devcontainer in the next tutorial.
5965

6066
- Required: `Remote Development`_
67+
- Required for Windows: `VSCode WSL2`_ (see `How to use WSL2 and Visual Studio Code`_)
6168
- Recommended: `VSCode EPICS`_
6269
- Recommended: `Kubernetes`_
63-
- Required for Windows: `VSCode WSL2`_ (see `How to use WSL2 and Visual Studio Code`_)
6470

6571
.. _VSCode WSL2: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl
6672
.. _How to use WSL2 and Visual Studio Code: https://code.visualstudio.com/blogs/2019/09/03/wsl2

0 commit comments

Comments
 (0)