Skip to content

Commit 31236b7

Browse files
callumforrestercallumforrester
committed
Split devcontainer tutorial into generic devcontainer and epics devcontainer
1 parent d70eb57 commit 31236b7

File tree

6 files changed

+155
-116
lines changed

6 files changed

+155
-116
lines changed

‎docs/user/images/dev-container-plugin.png

77.4 KB
Loading

‎docs/user/images/dev-container-settings.png

119 KB
Loading

‎docs/user/images/dev-container.png

79.4 KB
Loading

‎docs/user/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ side-bar.
1616
tutorials/intro
1717
tutorials/setup_workstation
1818
tutorials/devcontainer
19+
tutorials/epics_devcontainer
1920
tutorials/setup_k8s
2021
tutorials/create_beamline
2122
tutorials/deploy_example

‎docs/user/tutorials/devcontainer.rst

Lines changed: 25 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,35 @@ Setup the Devcontainer
55
Introduction
66
------------
77

8-
The devcontainer provides the environment in which you will do all your development
9-
and management of IOCs.
10-
11-
The base container is defined in https://github.com/epics-containers/dev-e7
12-
but we will use a customizable image derived from that. The customizable
13-
container definition is in https://github.com/epics-containers/.devcontainer.
8+
The devcontainer provides the environment in which you will do all your development.
149

1510

1611
Configure Visual Studio Code
1712
----------------------------
1813

14+
You must ensure you have the devcontainer plugin:
15+
16+
17+
.. figure:: ../images/dev-container-plugin.png
18+
:width: 600px
19+
:align: center
20+
21+
devcontainer plugin
22+
23+
1924
For podman users, you must first tell VSCode to use podman instead of docker.
2025
Open a VSCode window and hit "ctrl ," (control-comma) to open the user
2126
settings editor and search for
2227
"dev.containers.dockerPath", change its value from "docker" to "podman".
2328

2429

30+
.. figure:: ../images/dev-container-settings.png
31+
:width: 600px
32+
:align: center
33+
34+
devcontainer podman setting
35+
36+
2537
Launching the Devcontainer
2638
--------------------------
2739

@@ -49,116 +61,13 @@ to reopen the folder in a container. Click on the ``Reopen in Container`` button
4961

5062
reopen in container dialogue
5163

52-
Now all of your VSCode terminals and file explorer will be running inside of
53-
the devcontainer and have access to all the tools installed there.
54-
55-
To verify things are working as expected, open a terminal in VSCode from
56-
the menus ``Terminal > New Terminal``. You should see a prompt like this:
57-
58-
.. code-block:: bash
59-
60-
[E7][work-ec]$
61-
62-
The E7 is used to indicate that you are running inside the
63-
``dev-e7`` developer container.
64-
``work-ec`` is the name of the current working directory. You are
65-
welcome to alter the prompt by changing PS1 in ``.bashrc_dev`` (see next
66-
section), but it is a good idea to keep an indication of the container
67-
name in the prompt.
68-
69-
Things to note:
70-
71-
- Your workspace folder is mounted inside the container at the same path as
72-
the host folder it is mapped to. This means that you can edit files in
73-
the container and the changes are reflected outside the container and
74-
vice versa.
75-
76-
- Your home folder is also mounted in its usual location. BUT $HOME is set
77-
to ``/root``.
78-
79-
- Podman users are running as root inside the container but files will be
80-
written with your user id and group id when writing to the mounted
81-
workspace folder (or your home directory).
82-
83-
.. _devcontainer-configure:
84-
85-
Configuring the Devcontainer
86-
----------------------------
87-
88-
.. note::
64+
You can also access the command via the CTRL+SHIFT+P menu:
8965

90-
**DLS users**: the settings in the default ``.bashrc_dev`` are already
91-
configured for interacting with the test beamline bl01t on the test
92-
cluster Pollux. HOWEVER: for this exercise we will use your personal
93-
GitHub account to avoid clashes with other users of this tutorial.
94-
Therefore follow the instructions below and set KUBECONFIG as follows:
95-
96-
.. code-block:: bash
97-
98-
# point at your cluster configuration file
99-
export KUBECONFIG=/home/${USER}/.kube/config_pollux
100-
101-
To enable access to the pollux cluster, execute the following commands
102-
from OUTSIDE of the dev container:
103-
104-
.. code-block:: bash
105-
106-
module load pollux
107-
klogout
108-
.devcontainer/dls-copy-k8s-crt.sh # a script in the .devcontainer repo
109-
kubectl get nodes
110-
111-
The last command will ask for your fed-id and password and then show a
112-
list of nodes in the pollux cluster. Your credentials are cached for a
113-
week after which you will see authentication errors. To fix this
114-
repeat the above steps.
115-
116-
You devcontainer environment is configured by a file called
117-
``.bashrc_dev`` file. The terminals in the devcontainer will source this
118-
file when they start.
119-
120-
Much of this file is setting up convenience features like the prompt and bash
121-
history. You can change these to suit your own preferences.
122-
123-
The primary configuration options are the environment variables exported by
124-
this script. These are listed below with some recommended values for running
125-
these tutorials. Paste the following into the ``.bashrc_dev`` file and
126-
add your GitHub organization or user to K8S_HELM_REGISTRY.
127-
128-
.. code-block:: bash
129-
130-
############ REPLACE all environment below with your details ###################
131-
132-
# point at your cluster config file
133-
export KUBECONFIG=/home/${USER}/.kube/config
134-
135-
# the default domain for ec commands (REMOVE if this is supplied by the host)
136-
export K8S_DOMAIN=bl01t
137-
138-
# where to get HELM charts for ec commands
139-
export K8S_HELM_REGISTRY=ghcr.io/<YOUR GITHUB USER OR ORGANIZATION>
140-
141-
################################################################################
142-
143-
After editing ``.bashrc_dev`` you will need to close any open terminals and
144-
restart them to pick up the changes.
145-
146-
147-
.. Note::
148-
149-
For advanced users with knowledge of docker or podman.
150-
151-
You can also alter the parameters for launch of the container by editing the
152-
``.devcontainer/devcontainer.json`` file.
153-
`See here for details <https://containers.dev/implementors/json_reference/>`_
154-
155-
In addition, you can alter the system packages installed in the container or make
156-
any other changes to the Dockerfile and regenerate your own container image.
157-
158-
To pick up such changes to ``.devcontainer`` run the ``Rebuild Container``
159-
command from VSCode command pallette (accessed via ctrl-shift-P).
66+
.. figure:: ../images/dev-container.png
67+
:width: 600px
68+
:align: center
16069

161-
If you wish to persist these changes
162-
then it is suggested that you make your own github repo of .devcontainer and
163-
push the changes there.
70+
devcontainer launch option
16471

72+
Now all of your VSCode terminals and file explorer will be running inside of
73+
the devcontainer and have access to all the tools installed there.

‎docs/user/tutorials/epics_devcontainer.rst

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
2+
The EPICS Devcontainer
3+
======================
4+
5+
Introduction
6+
------------
7+
8+
Youc can setup a single devcontainer for managing all of your IOCs.
9+
10+
The base container is defined in https://github.com/epics-containers/dev-e7
11+
but we will use a customizable image derived from that. The customizable
12+
container definition is in https://github.com/epics-containers/.devcontainer.
13+
14+
.. seealso:: Basic devcontainer setup: `./devcontainer`
15+
16+
17+
Launching the Devcontainer
18+
--------------------------
19+
20+
Having setup your devcontainer, to verify things are working as expected,
21+
open a terminal in VSCode from the menus ``Terminal > New Terminal``.
22+
You should see a prompt like this:
23+
24+
.. code-block:: bash
25+
26+
[E7][work-ec]$
27+
28+
The E7 is used to indicate that you are running inside the
29+
``dev-e7`` developer container.
30+
``work-ec`` is the name of the current working directory. You are
31+
welcome to alter the prompt by changing PS1 in ``.bashrc_dev`` (see next
32+
section), but it is a good idea to keep an indication of the container
33+
name in the prompt.
34+
35+
Things to note:
36+
37+
- Your workspace folder is mounted inside the container at the same path as
38+
the host folder it is mapped to. This means that you can edit files in
39+
the container and the changes are reflected outside the container and
40+
vice versa.
41+
42+
- Your home folder is also mounted in its usual location. BUT $HOME is set
43+
to ``/root``.
44+
45+
- Podman users are running as root inside the container but files will be
46+
written with your user id and group id when writing to the mounted
47+
workspace folder (or your home directory).
48+
49+
.. _devcontainer-configure:
50+
51+
Configuring the Devcontainer
52+
----------------------------
53+
54+
.. note::
55+
56+
**DLS users**: the settings in the default ``.bashrc_dev`` are already
57+
configured for interacting with the test beamline bl01t on the test
58+
cluster Pollux. HOWEVER: for this exercise we will use your personal
59+
GitHub account to avoid clashes with other users of this tutorial.
60+
Therefore follow the instructions below and set KUBECONFIG as follows:
61+
62+
.. code-block:: bash
63+
64+
# point at your cluster configuration file
65+
export KUBECONFIG=/home/${USER}/.kube/config_pollux
66+
67+
To enable access to the pollux cluster, execute the following commands
68+
from OUTSIDE of the dev container:
69+
70+
.. code-block:: bash
71+
72+
module load pollux
73+
klogout
74+
.devcontainer/dls-copy-k8s-crt.sh # a script in the .devcontainer repo
75+
kubectl get nodes
76+
77+
The last command will ask for your fed-id and password and then show a
78+
list of nodes in the pollux cluster. Your credentials are cached for a
79+
week after which you will see authentication errors. To fix this
80+
repeat the above steps.
81+
82+
You devcontainer environment is configured by a file called
83+
``.bashrc_dev`` file. The terminals in the devcontainer will source this
84+
file when they start.
85+
86+
Much of this file is setting up convenience features like the prompt and bash
87+
history. You can change these to suit your own preferences.
88+
89+
The primary configuration options are the environment variables exported by
90+
this script. These are listed below with some recommended values for running
91+
these tutorials. Paste the following into the ``.bashrc_dev`` file and
92+
add your GitHub organization or user to K8S_HELM_REGISTRY.
93+
94+
.. code-block:: bash
95+
96+
############ REPLACE all environment below with your details ###################
97+
98+
# point at your cluster config file
99+
export KUBECONFIG=/home/${USER}/.kube/config
100+
101+
# the default domain for ec commands (REMOVE if this is supplied by the host)
102+
export K8S_DOMAIN=bl01t
103+
104+
# where to get HELM charts for ec commands
105+
export K8S_HELM_REGISTRY=ghcr.io/<YOUR GITHUB USER OR ORGANIZATION>
106+
107+
################################################################################
108+
109+
After editing ``.bashrc_dev`` you will need to close any open terminals and
110+
restart them to pick up the changes.
111+
112+
113+
.. Note::
114+
115+
For advanced users with knowledge of docker or podman.
116+
117+
You can also alter the parameters for launch of the container by editing the
118+
``.devcontainer/devcontainer.json`` file.
119+
`See here for details <https://containers.dev/implementors/json_reference/>`_
120+
121+
In addition, you can alter the system packages installed in the container or make
122+
any other changes to the Dockerfile and regenerate your own container image.
123+
124+
To pick up such changes to ``.devcontainer`` run the ``Rebuild Container``
125+
command from VSCode command pallette (accessed via ctrl-shift-P).
126+
127+
If you wish to persist these changes
128+
then it is suggested that you make your own github repo of .devcontainer and
129+
push the changes there.

0 commit comments

Comments
 (0)