Set up a Developer Workstation#

This page gets your workstation ready for the rest of the tutorials. By the end you will have the handful of tools the tutorials rely on:

  • Visual Studio Code — the recommended editor, for its devcontainer, Kubernetes, YAML and EPICS integration.

  • A container platform — podman (recommended) or docker, plus docker compose.

  • uv — installs and runs the Python CLI tools (copier and ec).

  • git — configured for your user with access to your repositories.

  • Python 3.13+ — optional; uv can provide it for you.

Not using VSCode? You can use any editor — see Working with your own code editor.

Note

Personal Access Tokens (PAT). On an untrusted machine, authenticate to GitHub with a fine-grained PAT (Settings → Developer Settings → Personal access tokens) scoped to Repository Contents and Workflows, rather than an SSH key. Cache it so you are not prompted repeatedly:

git config --global credential.helper 'cache --timeout 18000'

When prompted, enter your username and the PAT as the password. With a PAT, clone over https://github.com/... rather than git@github.com:....

Platform support#

The tutorial container images are x86_64 Linux. The best experience is an Intel Linux workstation or laptop (arm64 images exist but are less widely tested). On any other platform you have two options:

  • run the container runtime natively — see the quickstart;

  • or use the pre-built VirtualBox appliance below.

Either way you only need an internet connection to download the software and images. (At DLS you do not need DLS network resources — just the internet.)

Platform

Route

Any Linux (incl. DLS RHEL 8)

Installation Steps

Windows

VirtualBox Appliance, or WSL2 + Podman Desktop

Mac (Intel or Apple silicon)

VirtualBox Appliance, or Podman Desktop

VirtualBox Appliance#

If you are on Mac or Windows and would rather not configure a container runtime natively, use the Linux VM we provide with everything pre-installed. If you already have a Linux machine with admin rights, skip to Installation Steps instead.

  1. Install VirtualBox.

  2. Download the virtual machine (an OVA file) and import it with File → Import Appliance. The default resources are fine; 8 GB RAM and 4 CPUs is a sensible minimum.

  3. Start the VM and log in as ec-demo / demo1.

The VM ships with Ubuntu 22.04, Python 3.13, VSCode, podman and a zsh shell. To personalise it you only need to set up your git credentials and install the Python CLI tools — jump to Command line completion (optional), then Python (optional).

Installation Steps#

On your own Linux machine, work through the sections below.

VSCode#

Note

DLS users: load it with module load vscode, then open your project with code ..

Download and install VSCode, then add the extensions you need. Only the first is required before the next tutorial; the devcontainer installs the in-container extensions (Python, YAML, EPICS, Ansible, …) for you.

Podman#

We recommend podman because it is rootless by default — simpler and more secure for developing and running IOCs (see Rootless vs Rootful). Version 4.0 or later is required; it is tested on RHEL 8 and Ubuntu 22.04+.

Note

DLS users: RHEL 8 workstations ship podman 4.9.4 (RHEL 7 is not supported). The first time you use podman on a DLS machine, run the shared setup script:

/dls_sw/apps/setup-podman/setup.sh

Note

Prefer docker? epics-containers fully supports docker too. The tutorials say podman throughout, but every command has an identical docker equivalent; see Using Docker Instead of Podman for how to install it and the couple of extra steps rootful docker needs in devcontainers.

Docker Compose for podman users#

docker compose runs a set of IOCs and other services together. The early tutorials use it before moving on to Kubernetes, and it can also underpin a non-Kubernetes production deployment.

Follow the Docker Compose Quickstart to install docker compose and point it at podman.

Warning

Wayland / X11 displays. Several tutorials run GUI apps — notably Phoebus — inside containers, which need access to your X server. On Wayland, and some X11 setups, the container is refused and the app fails to open with an X11 authorization error. Grant the local user access once per login session before launching:

xhost +SI:localuser:$(id -un)

Command line completion (optional)#

Shell completion makes podman much easier to explore. Run once:

# bash
mkdir -p ~/.local/share/bash-completion/completions
podman completion bash > ~/.local/share/bash-completion/completions/podman

# zsh (oh-my-zsh)
mkdir -p ~/.oh-my-zsh/completions
podman completion zsh > ~/.oh-my-zsh/completions/_podman

Python (optional)#

The CLI tools need Python 3.13 or later. You do not have to install it yourself — uv (next) can manage Python versions for you. If you would rather use a system Python, see the installation guide.

Note

DLS users: module load python/3.13.

uv#

We use uv to install and run the Python CLI tools (copier and ec). It installs each tool into its own isolated environment and puts it on your PATH, so there is no virtual environment to activate.

Note

DLS users: module load uv instead of running the installer below.

curl -LsSf https://astral.sh/uv/install.sh | sh

See the uv install docs for other methods (including Windows).

copier and ec#

copier stamps out the templates for services repositories and generic IOCs. Install it now, along with ec (the edge-containers CLI used in the Kubernetes tutorials):

uv tool install copier
uv tool install edge-containers-cli

Both are now on your PATH in every new shell — nothing to activate. Upgrade later with uv tool upgrade --all. If a freshly installed tool is not found, run uv tool update-shell and open a new shell.

git#

Install git if you do not have it, then set your identity:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Set up credentials for your GitHub repositories using either a PAT (see the note at the top of this page) or an SSH key.

Kubernetes#

You do not need Kubernetes yet. The next tutorials create, deploy and debug IOCs locally by deploying containers to your workstation’s podman with docker compose. Kubernetes comes later.