Benjamin LabrecqueandClaude Sonnet 5
99b5cd9e1e
Docs are rendered on a separate site (zensical), which only serves the docs/ tree, so relative links out to config/services_registry.yml were broken there. Point them at the Gitea file view instead. Left the add-new-service.md -> ioc/iocs_overview.md link relative since it stays within the docs tree. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A9GjKvXCmfgJpKzbQdZ7UA
3.6 KiB
Adding a new service
Python setup
Install the uv package manager
CLI (Command-Line Interface)
We have our own cli called agebd.
To use the cli, first clone this repo. Then:
cd cli
uv sync
source .venv/bin/activate
agebd --help
Adding a new service
agebd service add --help
This command has side effects you should know about before running it. It requires a clean working tree, then it:
- Assigns the service the next free IOC port and registers it in
config/services_registry.yml. - Adds the service to
AGEBD-CPCL-MASTER's IOC pattern file, so it gets the standard ALH lifecycle PVs (AGEBD-ALH$(SUFFIX):$(SERVICE)-*) and appears in theServiceManagerGUI screen. - Appends a row to
iocs_overview.md. - Creates a new branch
feature/add-service-<name>, scaffolds the new service's files from the templates, and pushes the branch automatically — you don't rungit pushyourself.
Pushing that branch triggers the Add new service Gitea Actions workflow
(.gitea/workflows/add-new-service.yml), which deploys master, installs/restarts its IOC,
deploys your new service, and installs/starts its own IOC — all in dev. Check the Actions
tab for that run to confirm it succeeded before doing anything else with the new service.
Environments
The services are deployed to 2 environments:
| Environment | Network | Host | Deploy path on host |
|---|---|---|---|
prod |
machine |
sls-vserv-bd-hla01 |
/sls/bd/hla/prod/ |
dev |
office |
sls-vserv-bd-hla01-dev |
/sls/bd/hla/dev/ |
Process Variables (PVs)
We distinguish between
prodvsdevPVs- service specific PVs from a dedicated IOC vs external PVs from other IOCs
PVs - Service Specific
These are defined as EPICS records in your service's own services/<name>/current/ioc/*.template
file, instantiated by services/<name>/current/ioc/AGEBD-CPCL-<NAME>_main.subs.
prod and dev PVs automatically get created: at deploy time, {{ agebd_env_suffix_upper }}/
{{ agebd_env_suffix_lower }} placeholders in those files are substituted with -DEV/-dev
in dev, or left empty in prod (see .gitea/scripts/deploy-service.sh).
In your code, you only use the prod name of a PV, e.g. PV("AGEBD-MYSERVICE:MYPVNAME").
The PVLink/DevPVLink framework (packages/agebd/src/agebd/pv.py) automatically appends
-DEV when the service runs in dev — but only for PVs belonging to your own service,
plus AGEBD-ALH/AGEBD-MASTER. See "External" below for PVs owned by another service.
PVs - External
PVs owned by another service (including another AGEBD service, e.g. AGEBD-PARAMS:... used
from a different service) or by real accelerator hardware (e.g. ARS01-MOCT-...) are used
verbatim — no -DEV suffix is ever added, even in dev.
PVs - Examples
| Environment | Service Specific | External |
|---|---|---|
prod |
PV("AGEBD-MYSERVICE:MYPVNAME") read&write |
PV("AGEOP-SOME-SERVICE:SOME-PVNAME") read&write |
dev |
PV("AGEBD-MYSERVICE-DEV:MYPVNAME") read&write |
PV("AGEOP-SOME-SERVICE:SOME-PVNAME") readonly |
Python
For python services there are 3 environments. The python environment is set through the env variable AGEBD_ENV.
| Environment | PVs |
|---|---|
AGEBD_ENV=prod |
uses prod PVs |
AGEBD_ENV=dev |
uses dev PVs |
AGEBD_ENV=local |
uses fake/mock python objects as PVs, no access to real PVs |