Skip to content

Commit 3449bcf

Browse files
gilesknapgilesknap
authored
Merge pull request #25 from epics-containers/split-devcontainer
Split devcontainer tutorial into generic and epics devcontainer
2 parents d70eb57 + ef36ddd commit 3449bcf

File tree

6 files changed

+187
-128
lines changed

6 files changed

+187
-128
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: 35 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,56 @@
11

2-
Setup the Devcontainer
3-
======================
2+
Setup a Devcontainer
3+
====================
44

55
Introduction
66
------------
77

8-
The devcontainer provides the environment in which you will do all your development
9-
and management of IOCs.
8+
The devcontainer provides the environment in which you will do all your development.
9+
This is a basic tutorial that introduces the concept in preparation for the
10+
epics devcontainer tutorial.
1011

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.
12+
.. seealso:: `epics_devcontainer`
1413

1514

1615
Configure Visual Studio Code
1716
----------------------------
1817

18+
You must ensure you have the devcontainer plugin:
19+
20+
21+
.. figure:: ../images/dev-container-plugin.png
22+
:width: 600px
23+
:align: center
24+
25+
devcontainer plugin
26+
27+
1928
For podman users, you must first tell VSCode to use podman instead of docker.
2029
Open a VSCode window and hit "ctrl ," (control-comma) to open the user
2130
settings editor and search for
2231
"dev.containers.dockerPath", change its value from "docker" to "podman".
2332

2433

25-
Launching the Devcontainer
26-
--------------------------
34+
.. figure:: ../images/dev-container-settings.png
35+
:width: 600px
36+
:align: center
2737

28-
To setup your devcontainer, perform the following steps:
38+
devcontainer podman setting
2939

30-
- create a workspace folder
31-
- clone the .devcontainer repository into the workspace folder
32-
- open the workspace folder with Visual Studio Code.
3340

34-
for example:
41+
Launching the Devcontainer
42+
--------------------------
43+
44+
If your repository contains a ``.devcontainer`` directory, vscode will be
45+
able to follow the instructions inside and launch a container.
3546

3647
.. code-block:: bash
3748
38-
mkdir work-ec
39-
cd work-ec
40-
git clone [email protected]:epics-containers/.devcontainer.git
49+
git clone <repo>
50+
cd <repo>
4151
code .
4252
43-
This will open the workspace folder in Visual Studio Code. You will be prompted
53+
This will open the project folder in Visual Studio Code. You will be prompted
4454
to reopen the folder in a container. Click on the ``Reopen in Container`` button.
4555

4656
.. figure:: ../images/vscode-reopen-in-container.png
@@ -49,116 +59,13 @@ to reopen the folder in a container. Click on the ``Reopen in Container`` button
4959

5060
reopen in container dialogue
5161

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::
89-
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 ###################
62+
You can also access the command via the CTRL+SHIFT+P menu:
13163

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).
64+
.. figure:: ../images/dev-container.png
65+
:width: 600px
66+
:align: center
16067

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.
68+
devcontainer launch option
16469

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

‎docs/user/tutorials/epics_devcontainer.rst

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

0 commit comments

Comments
 (0)