sls/hla_framework_bd
0
1
Fork 0
Code Issues 28 Pull Requests 2 Actions Packages Projects 1 Releases Wiki Activity

docs: refactor into user and developer docs

Browse Source
This commit is contained in:
Benjamin Labrecque
2026-07-21 16:40:41 +02:00
parent 440f4eb005
commit 2a74d1e2be
11 changed files with 4 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer/ansible.md
+36
View File
@@ -0,0 +1,36 @@
# Ansible
## Running a playbook manually
Set vars on command line:
```
ansible-playbook ansible/playbooks/add-new-service.yml \
-i ansible/hosts.yml \
--extra-vars="repo_root=${{ github.workspace }} agebd_env=dev service_name_lower=<service dir name>" \
-v
```
### Install an IOC
```
ansible-playbook ansible/playbooks/ioc-install.yml \
-i ansible/hosts.yml \
--extra-vars="agebd_env=dev branch_name=feature/add-service-playground service_name_lower=playground ioc_port=50003" \
-v
```
### Start an IOC
```
ansible-playbook ansible/playbooks/ioc-start.yml \
-i ansible/hosts.yml \
--extra-vars="service_name_lower=playground ioc_port=50003" \
-v
```
### Restart an IOC
```
ansible-playbook ansible/playbooks/ioc-restart.yml \
-i ansible/hosts.yml \
--extra-vars="agebd_env=dev branch_name=feature/add-service-playground service_name_lower=playground" \
-v
```
docs/developer/caget.md
+12
View File
@@ -0,0 +1,12 @@
# Using `caget` to check the values of PVs
```
ssh sls-lc
```
On sls-lc or sls-vserv-bd-hla01-dev:
```
ca office network
export EPICS_CA_ADDR_LIST="129.129.130.255 129.129.131.255 129.129.137.255 129.129.158.255 129.129.217.255 129.129.150.255 129.129.152.255 sls-cagw.psi.ch:5062"
caget AGEBD-PLAYGROUND-DEV:AO
```
docs/developer/cicd_runner.md
+130
View File
@@ -0,0 +1,130 @@
# CI/CD Runner
## Host
TODO: Should we have a dedicated runner server?
sls-vserv-bd-01-dev
## Setup
Resources:
- https://docs.gitea.com/usage/actions/act-runner
- https://linux.psi.ch/documentation/services/gitea/gitea-runner/
TODO: add commands we ran with Basil in the meeting
TODO: need to regenerate `~/gitea-runner/.runner` with correct label `hla-dev`
```shell
<install command>
sudo su svcusr-sls2hla
# Set up hla deployment dir
mkdir /sls/bd/hla
chmod 755 /sls/bd/hla
...
mkdir ~/.local/bin
# Install Node -- required for actions like repo checkout
cd /tmp
curl -LO https://nodejs.org/dist/v20.11.1/node-v20.11.1-linux-x64.tar.xz
tar -xf node-v20.11.1-linux-x64.tar.xz --strip-components=2 -C ~/.local/bin/ node-v20.11.1-linux-x64/bin/
rm node-v20.11.1-linux-x64.tar.xz
```
## Manually run the runner
```shell
sudo su svcusr-sls2hla
/usr/local/bin/act_runner daemon
```
## Run the runner as a systemd service
Edit the service file `/etc/systemd/system/act_runner.service`:
```toml
[Unit]
ConditionPathExists=/etc/act_runner/config.yaml
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
After=podman.socket
Requires=podman.socket
[Service]
User=svcusr-sls2hla
WorkingDirectory=/home/svcusr-sls2hla/gitea-runner
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutSec=0
RestartSec=10
Restart=always
[Install]
WantedBy=multi-user.target
```
As your own user (not `svcusr-sls2hla`; need access to sudo):
```
# 1. Install Podman
sudo dnf install -y podman
# 2. Enable and start the system-wide Podman socket
sudo systemctl enable --now podman.socket
# 3. Create the symlink so the Gitea runner finds Podman at the expected Docker path
sudo ln -s /run/podman/podman.sock /var/run/docker.sock
# 4. Create podman group
sudo groupadd podman
# 5. Add service user to this new group
sudo usermod -aG podman svcusr-sls2hla
```
Configure podman socket:
```
sudo systemctl edit podman.socket
```
add this to the file:
```
[Socket]
SocketMode=0660
SocketGroup=podman
```
Enable and restart:
```
# Enable act_runner
sudo systemctl enable --now act_runner
# Reload configurations
sudo systemctl daemon-reload
# Restart the socket so it applies the new group owner
sudo systemctl restart podman.socket
# Fire up the runner
sudo systemctl restart act_runner.service
```
### Check logs of systemd service
```
sudo su svcusr-sls2hla
journalctl -u act_runner.service -n 20
```
## User
The gitea actions run as user `svcusr-sls2hla`
## Auth
### #TODO: this is a temporary workaround
I created an ssh key on `sls-vserv-bd-hla01-dev` (where the runner runs), and added the public key to my
gitea profile ssh keys. That way the `svcusr` can clone the repos I can clone.
docs/developer/ioc/ioc.md
+91
View File
@@ -0,0 +1,91 @@
# IOC
TODO: some iocs not associated to a service, where to put?
TODO: need to dev/prod template them too
## Host
sls-vserv-bd-01(-dev)
## Shell
Start up an IOC shell:
```shell
iocsh AGEBD-CPCL-MASTER_main.subs
```
then you can run commands to interact with EPICS.
List available PVs:
```shell
> dbl
```
## Install
On `sls-lc*`
```shell
ioc install -V --ioc AGEBD-CPCL-TUNEFBX –clean
```
Result: on ioc host, e.g. `sls-vserv-bd-01-dev`
```shell
vim /etc/shellbox/<port-number>
```
## Check PVs of installed IOC
```shell
ioc shell AGEBD-CPCL-MASTER-DEV
```
```shell
> dbl
```
Exit:
```shell
Ctrl + d
```
Old docs: # TODO: merge with current
## IOC installation
The following instructions explain the basics of starting and managing IOCs on the IOC host.
For the initial install the shellbox on the ioc host must be restarted.
For existing IOCs a login to the IOC and restart via ctr+x is sufficient.
### local tests
#### using subs file
iocsh AGEBD-CPCL-PLAYGROUND_main.subs
#### using template file
iocsh PLAYGROUND.template DEVICE=TEST
### proper install
ioc install -V --ioc AGEBD-CPCL-PLAYGROUND --clean
ioc shell AGEBD-CPCL-PLAYGROUND
ctrl+x
### login on BD IOC host for access to shellbox
ssh sls-vserv-bd-01
#### shellbox
TODO: should be -bd-01?
cd /ioc/hosts/sls-vserv-op-01<br>
gedit shellbox.conf<br>
restart ioc via shellbox:<br>
sudo shellbox reload # new ioc installed<br>
sudo shellbox status # status of all iocs on server<br>
sudo shellbox stop 50045 # stop ioc<br>
sudo shellbox start 50045 # start ioc<br>
sudo shellbox log 50045 -f # log file (tail)<br>
exit # exit ssh<br>
docs/developer/python/epics.md
+70
View File
@@ -0,0 +1,70 @@
# EPICS
Where is EPICS Base (https://gitea.psi.ch/epics) installed?
```
echo $EPICS
```
Host architecture that EPICS Base runs on:
```
echo $EPICS_HOST_ARCH
```
Which channel access lib is being used in python?
```
[sls-vserv-bd-hla01-dev ~]$ which python
/bin/python
[sls-vserv-bd-hla01-dev playground]$ python3 -c "import ctypes; import epics.ca; print(epics.ca.find_libca())"
/usr/local/epics/base-7.0.9/lib/RHEL9-x86_64/libca.so
[sls-vserv-bd-hla01-dev ~]$ source /opt/gfa/python-3.10/latest/bin/activate
(base) [sls-vserv-bd-hla01-dev ~]$ which python
/opt/gfa/python-3.10/20220602/bin/python
(base) [sls-vserv-bd-hla01-dev ~]$ python3 -c "import ctypes; import epics.ca; print(epics.ca.find_libca())"
/opt/gfa/python-3.10/20220602/epics/lib/linux-x86_64/libca.so
```
How does the conda env configure which EPICS to use?
```
(base) [sls-vserv-bd-hla01-dev ~]$ cat /opt/gfa/python-3.10/20220602/etc/conda/activate.d/epics-base_activate.sh
export EPICS_BASE="/opt/gfa/python-3.10/20220602/epics"
export EPICS_HOST_ARCH="linux-x86_64"
export EPICS_BASE_HOST_BIN="/opt/gfa/python-3.10/20220602/epics/bin/linux-x86_64"
export EPICS_BASE_VERSION="7.0.5.0"
export PATH=$EPICS_BASE_HOST_BIN:$PATH
```
How does the conda env configure which EPICS python uses?
```
(base) [sls-vserv-bd-hla01-dev ~]$ cat /opt/gfa/python-3.10/20220602/etc/conda/activate.d/pyepics_activate.sh
export PYEPICS_LIBCA="${EPICS_BASE}/lib/${EPICS_HOST_ARCH}/libca.so"
```
Example reading from a PV:
```
[sls-vserv-bd-hla01-dev ~]$ /bin/python
Python 3.9.25 (main, Apr 17 2026, 00:00:00)
[GCC 11.5.0 20240719 (Red Hat 11.5.0-14)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from epics import PV
>>> pv = PV("AGEBD-PLAYGROUND-DEV:AO")
>>> pv.get()
5.0
>>>
```
## System python installed packages
```
/bin/python -m pip list -v
```
## Systemd Services
When ssh-ing into a machine, `/etc/profile.d/*` automatically gets sourced.
When running a `systemd` service, this does not happen.
That's why we need to source `/etc/profile.d/cas_12_epics.sh` in our startup script
to make sure that `EPICS` is configured properly.
docs/developer/python/pixi.md
+9
View File
@@ -0,0 +1,9 @@
# Pixi
## Install
```
curl -fsSL https://pixi.sh/install.sh | sh
```
installs in `${HOME}/.pixi/bin`
docs/developer/steps.md
+59
View File
@@ -0,0 +1,59 @@
# Manual steps to be automated
- [x] Define Name, e.g., TUNEFBX
- [x] Add to Master IOC
- In git repo gitea/A_BD https://gitea.psi.ch/epics_iocboot_sls/A_BD
- Edit AGEBD-CPCL-MASTER_main.subs
- Login on machine network and reinstall/restart master IOC
- Ssh sls-lca
- ioc install -V --ioc AGEBD-CPCL-MASTER –clean
- ioc shell AGEBD-CPCL-MASTER then ctrl + x
- [x] Add to Master Service
- In git repo gitea/sls_bd https://gitea.psi.ch/autodeploy_bin/sls_bd
- Edit AGEBD-SERVICE-MASTER.py to include
- Git push
- Restart master service
- [x] Prepare python file
- In git repo gitea/sls_bd https://gitea.psi.ch/autodeploy_bin/sls_bd
- Copy AGEBD-SERVICE-TEMPLATE.py to AGEBD-SERVICE-TUNEFBX.py
- [ ] Prepare IOC for new Service
- [x] In git repo gitea/A_BD https://gitea.psi.ch/epics_iocboot_sls/A_BD
- [x] Copy directory AGEBD-CPCL-TEMPLATE to AGEBD-CPCL-TUNEFBX
- [x] Update all filenames
- [x] Update all files
- [ ] Add required pvs to .template file
- [x] Add IOC to readme.md and find port number to be configured in yaml file
- [x] Git push
- [x] Initialize / Start IOC for new service
- Login on machine network and install the new IOC
- Ssh sls-lca
- Cd /sls/bd/
- ioc install -V --ioc AGEBD-CPCL-TUNEFBX –clean
- Login on BD IOC host for access to shellbox for initial start of new IOC
- ssh sls-vserv-bd-01
- sudo shellbox status
- sudo shellbox reload
- sudo shellbox status
- sudo shellbox start "port number"
- [x] Prepare systemd unit file
- In git repo gitea/sls_bd https://gitea.psi.ch/autodeploy_bin/sls_bd
- Copy systemd/AGEBD-SERVICE-TEMPLATE.service systemd/AGEBD-SERVICE-TUNEFBX.service
- Edit systemd/AGEBD-SERVICE-TUNEFBX.service for starting AGEBD-SERVICE-TUNEFBX.py
- [x] Initialize / Start systemd service
- Login on BD service host
- ssh sls-vserv-bd-hla01
- sudo su svcusr-sls2hla
- Check if systemctl is working : >>systemctl –user
- If return is "Failed to connect to bus: No such file or directory"
- export XDG_RUNTIME_DIR=/run/user/51393
- systemctl --user daemon-reload
- systemctl --user enable /sls/bd/bin/systemd/AGEBD-SERVICE-TUNEFBX.service
- systemctl --user start AGEBD-SERVICE-TUNEFBX.service
- [x] Add to Service overview GUI
- In git repo gitea/sls_bd_qt https://gitea.psi.ch/autodeploy_config/sls_bd_qt
- Add lines to service management gui for new service >> caqtdm_designer A_BD_ServiceManager.ui
- Test updated GUI: >> caqtdm A_BD_ServiceManager.ui
- [ ] Make GUI dedicated to new service
- In git repo gitea/sls_bd_qt https://gitea.psi.ch/autodeploy_config/sls_bd_qt
docs/developer/systemd-service.md
+8
View File
@@ -0,0 +1,8 @@
# Systemd Service
## Check all logs
```
sudo su svcusr-sls2hla
journalctl --user -u AGEBD-SERVICE-MASTER.service
```
docs/developer/ui.md
+23
View File
@@ -0,0 +1,23 @@
# UI
## CAQTDM
```
ssh -J sls-lc -X labrec_b@sls-vserv-bd-hla01-dev.psi.ch
```
also works?:
```
ssh hla-dev
```
Macro substitution
```
caqtdm -m'TESTAGEBDALH=AGEBD-ALH' A_BD_ServiceManager.ui
```
`caqtdm` does not exists when using `svcusr-sls2hla`
# TODO: dev/prod ui
# TODO: remove/delete old autodeployed ui files
# TODO: not 1-to-1, eg several use TUNE ui