Runtime Support (ibek-runtime-support)#

Runtime support lets you add DB templates ibek entity definitions to one or more IOC instances without recompiling the generic IOCs that they use.

Note that the ibek entity definitions can add to the startup script entires of the IOC instance as well as to its expanded database.

This can be used for facility-wide shared definitions (like AreaDetector plugin sets) as well as beamline-specific templates — anything that is purely declarative (DB templates, entity models with sub_entities) rather than compiled code.

Why use runtime support?#

In epics-containers, Generic IOC images are shared across beamlines. Compiling every DB template and entity definition into the image would either bloat it or force you to create many near-identical one-off containers. Runtime support solves this by letting you supply .ibek.support.yaml files (and their associated DB templates) from outside the container. ibek picks them up at boot time and treats them exactly like built-in support definitions.

This works for both facility-wide definitions (shared across all beamlines via a git submodule) and beamline-specific templates (committed directly to your services repo). The principle is the same as referencing a DB template via the databases entry in a genric IOC’s support YAML — the only difference is that the files come from the services repo at runtime instead of from inside the container filesystem.

There are two levels of sharing:

Level	Where it lives	Example
Facility-wide	A shared submodule under `ibek-runtime-support/`	`ibek-runtime-support-dls` (contains `detectorPlugins`)
Beamline-specific	A folder directly in `ibek-runtime-support/`	`ibek-runtime-support/bl21i-support/`

Anything that requires compilation (e.g. aSub record C code) cannot use this mechanism — it must live in a compiled support module inside a Generic IOC image.

How it works#

At IOC boot time, ibek’s runtime generate command looks for entity model definitions in two places:

Built-in definitions — the .ibek.support.yaml files compiled into the Generic IOC image under /epics/ibek-defs/.
Config folder definitions — any .ibek.support.yaml files found in the IOC instance’s config/ folder, including symlinks (ibek follows symlinks when globbing).

It then loads instance YAML files in order:

ioc.yaml — the main IOC definition (entities from the Generic IOC’s built-in support).
runtime.yaml — additional entities that use runtime support definitions.

The entities from runtime.yaml are appended after those from ioc.yaml, so runtime entities appear at the end of the startup script.

Directory structure#

A typical services repo with runtime support looks like this:

my-beamline-services/
  ibek-runtime-support/
    my-beamline-support/                  # beamline-specific (committed directly)
      my-beamline-support.ibek.support.yaml
      myCustom.template                   # optional DB templates
    ibek-runtime-support-dls/             # facility-wide (git submodule)
      detectorPlugins.ibek.support.yaml
    runtime.schema.json                   # auto-generated by pre-commit
  services/
    bl21i-di-dcam-01/
      config/
        ioc.yaml
        runtime.yaml
        detectorPlugins.ibek.support.yaml -> ../../../ibek-runtime-support/ibek-runtime-support-dls/detectorPlugins.ibek.support.yaml

The key detail is the symlink in the IOC’s config/ folder. ibek only looks inside config/ for support definitions, so you must symlink in each .ibek.support.yaml file that the IOC needs. This is deliberate — it means each IOC explicitly declares which runtime support it uses.

Setting up runtime support in your services repo#

1. Update your services repo template#

Make sure your services repo is on template version 5.2.0 or later:

uvx copier update -A
# fix any merge conflicts
git commit -am "update services repo to latest template"
git push

2. Add the facility-wide submodule (if needed)#

If your IOCs use AreaDetector and you want the standard detectorPlugins entities, add the shared submodule:

cd ibek-runtime-support
git submodule add https://gitlab.diamond.ac.uk/controls/containers/utils/ibek-runtime-support-dls.git

3. Create a beamline-specific support folder (if needed)#

For DB templates or entity models specific to your beamline, create a folder directly under ibek-runtime-support/:

mkdir ibek-runtime-support/bl21i-support

Add a support YAML file — for example, a custom template that loads a DB file:

# ibek-runtime-support/bl21i-support/bl21i-support.ibek.support.yaml
# yaml-language-server: $schema=https://github.com/epics-containers/ibek/releases/download/3.0.1/ibek.support.schema.json

module: bl21i-support

entity_models:
  - name: myCustomDevice
    description: A beamline-specific device template
    parameters:
      P:
        type: str
        description: PV prefix
      PORT:
        type: str
        description: Asyn port name
    databases:
      - file: myCustom.template
        args:
          P:
          PORT:

Place the corresponding myCustom.template file in the same folder. ibek will find it via the symlink (see below).

4. Generate the runtime schema#

The runtime schema provides auto-completion and validation for runtime.yaml files. It is generated automatically by a pre-commit hook:

uvx pre-commit run --all-files

This runs ibek ioc generate-schema over all .ibek.support.yaml files in ibek-runtime-support/ and writes runtime.schema.json. Commit the generated schema alongside your support YAML.

Using runtime support in an IOC instance#

1. Symlink the support YAML into config#

For each runtime support YAML your IOC needs, create a symlink in its config/ folder:

cd services/bl21i-di-dcam-01/config

# facility-wide detector plugins
ln -s ../../../ibek-runtime-support/ibek-runtime-support-dls/detectorPlugins.ibek.support.yaml .

# beamline-specific support (if you have one)
ln -s ../../../ibek-runtime-support/bl21i-support/bl21i-support.ibek.support.yaml .

Only symlink what the IOC actually uses — don’t symlink everything.

Tip

Don’t forget to also symlink DB Templates if your runtime support yaml uses them

2. Create runtime.yaml#

Add a runtime.yaml to the IOC’s config/ folder. The schema reference at the top gives you auto-completion in VS Code (with the Red Hat YAML extension):

# yaml-language-server: $schema=../../../ibek-runtime-support/runtime.schema.json
ioc_name: "{{ _global.get_env('IOC_NAME') }}"
description: additional entities from the services repo

entities:
  - type: detectorPlugins.detectorPlugins
    P: BL21I-DI-DCAM-01
    CAM: D1.CAM
    PORTPREFIX: D1

The type field uses the format module.entityName, where module matches the module: field in the support YAML and entityName matches the entity model’s name:.

3. Commit and deploy#

git add -A
git commit -m "add runtime support for bl21i-di-dcam-01"
git push

Deploy with ec as usual. ibek will load both ioc.yaml and runtime.yaml at boot time.

Example: using detectorPlugins for an AreaDetector IOC#

The detectorPlugins support YAML (in ibek-runtime-support-dls) is a facility-wide shared definition for AreaDetector IOCs. It provides two entity models:

Entity	Description
`detectorPlugins.detectorPlugins`	Lean set of AreaDetector plugins for Bluesky/Ophyd (PVA, Stats, ROIStat, HDF5)
`detectorPlugins.gdaPlugins`	Full legacy plugin set for GDA (ROIs, StdArrays, Stats, Process, Overlay, TIFF, HDF5, PVA, ROIStat, MJPG)

Both are composed entirely of sub_entities referencing ADCore types, so they work with any Generic IOC that includes ADCore — no extra compilation needed.

Typical setup#

Your ioc.yaml defines the camera and basic infrastructure:

entities:
  - type: ADAravis.aravisCamera
    P: BL21I-DI-DCAM-01
    PORT: D1.CAM
    # ... other camera params

Your runtime.yaml adds the plugins:

entities:
  - type: detectorPlugins.detectorPlugins
    P: BL21I-DI-DCAM-01
    CAM: D1.CAM
    PORTPREFIX: D1

This wires up PVA, Stats, ROIStat, and HDF5 plugins — everything Bluesky/Ophyd needs for standard data collection. Use gdaPlugins instead if you need the full legacy GDA plugin set.

Tips#

Schema validation catches errors early. Always reference the runtime schema at the top of runtime.yaml. VS Code will underline invalid entity types or missing parameters immediately.
Keep runtime support lean. If a support module is used by many beamlines and requires compilation, it belongs in a Generic IOC image, not in runtime support.
DB templates go next to their support YAML. When ibek follows the symlink to load the .ibek.support.yaml, it also searches that directory for .template files referenced in databases: entries.
One symlink per support YAML. Don’t symlink the entire ibek-runtime-support/ folder — symlink individual .ibek.support.yaml files so each IOC explicitly declares its dependencies.
Regenerate the schema when support YAML changes. Run uvx pre-commit run --all-files after editing any .ibek.support.yaml under ibek-runtime-support/ to keep the schema up to date.