| name | dtwin-tango-runbook |
| description | SOLEIL-oriented TANGO runbook for dt4acc, including Tango DB container startup, private data prerequisites, and the recommended debug order after the public host smoke test. |
| version | 1.0.0 |
dtwin-tango-runbook
When to Use
SOLEIL-oriented TANGO runbook for dt4acc, including Tango DB container startup, private data prerequisites, and the recommended debug order after the public host smoke test.
Overview
This skill contains a reusable operational workflow. Follow the existing task-specific steps and examples in the sections below.
Pitfalls
- Do not hardcode credentials, tokens, or personal secrets.
- Verify external service URLs, paths, and permissions before making changes.
- Keep generated outputs reproducible and record input assumptions.
Verification
- Confirm required inputs and credentials are available.
- Run the smallest safe command or example before scaling up.
- Check produced files, API responses, or plots before reporting success.
Use this runbook when the goal is to start or debug the TANGO version of the dt4acc digital twin.
Trigger Conditions
- User wants to run the SOLEIL TANGO twin
- User wants to debug TANGO startup
- User asks why the public repos are not enough for the TANGO path
- User already validated the public/core stack and now needs the facility-specific TANGO stage
Key Difference vs EPICS
The TANGO path is not the fastest current startup path.
Developers report that, for now, the EPICS version starts faster. Use TANGO only when you specifically need the TANGO device-server workflow.
Critical Extra Prerequisites
The public repos alone are not sufficient for the SOLEIL TANGO twin.
You additionally need:
1. Tango DB container running first
apptainer run oras://gitlab-registry.synchrotron-soleil.fr/software-control-system/containers/apptainer/tango:latest
2. Private SOLEIL data present locally
~/Documents/dt4acc_soleil_twin_data
This data is intentionally not in git, because the SOLEIL lattice/configuration is not public.
Recommended Debug Order
- Validate the public/core stack first with the host smoke test
- Confirm the Tango DB container is running
- Confirm
~/Documents/dt4acc_soleil_twin_data exists and is populated
- Only then start/debug the TANGO twin
Step 1: Validate the public/core stack first
Before touching TANGO, run:
/tmp/dtwin-build/run_dtwin_host_smoke_test.sh /tmp/dtwin-build
If this fails, fix the public/core stack first. Do not start with TANGO debugging.
Step 2: Start Tango DB container
In a dedicated terminal:
apptainer run oras://gitlab-registry.synchrotron-soleil.fr/software-control-system/containers/apptainer/tango:latest
Keep it running.
Step 3: Verify private data directory
Check:
test -d ~/Documents/dt4acc_soleil_twin_data && echo OK || echo MISSING
If missing, the SOLEIL TANGO twin cannot be expected to start correctly.
Step 4: Prepare Python environment
If using the local-repo workflow:
cd /tmp/dtwin-build
python3 -m venv .venv-dt4acc-tango
source .venv-dt4acc-tango/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e /tmp/dtwin-build/dt4acc-lib
python3 -m pip install -e /tmp/dtwin-build/lat2db
python3 -m pip install -e /tmp/dtwin-build/dt4acc
You will also need the TANGO-specific Python/runtime pieces appropriate to the developer workflow in use.
Step 5: Start/debug the TANGO server path
The public repo contains the TANGO code under:
src/dt4acc/custom_tango/ioc/
Relevant components include:
server_manager.pysingle_server.py- device setup / controller modules under
devices/
The integration tests in:
dt4acc/tests/tango_tests/
show the intended behavior and expected device model.
What TANGO Tests Intend To Validate
The TANGO tests cover:
- device export/reachability
- twiss/orbit/tune propagation
- quadrupole write → recalculation
- steerer kick → orbit change
- reset behavior after divergence
These tests are meaningful only after the TANGO runtime prerequisites are satisfied.
Fast TANGO Triage Checklist
If the TANGO twin does not start, check these in order:
A. Public/core stack healthy?
/tmp/dtwin-build/run_dtwin_host_smoke_test.sh /tmp/dtwin-build
B. Tango DB running?
Was this started first?
apptainer run oras://gitlab-registry.synchrotron-soleil.fr/software-control-system/containers/apptainer/tango:latest
C. Private SOLEIL data present?
ls -ld ~/Documents/dt4acc_soleil_twin_data
D. TANGO-specific env/runtime configured?
Check TANGO_HOST, developer instructions, and whatever startup wrapper the current developer branch expects.
What Not To Assume
- Do not assume public GitHub repos alone are enough for the SOLEIL TANGO path.
- Do not interpret a TANGO startup failure as proof that
dt4acc itself is broken.
- Do not start with TANGO when EPICS would answer the user’s immediate need faster.
- Do not skip the Tango DB container step.
Upstream Documentation Note
Developers are improving the dt4acc READMEs on:
dt4acc/dt4acc:dev/feature/updated-readme
But they also said this is not fully ready yet, because required PRs still need to land in dev/main.
So for the TANGO path, prefer direct developer guidance over assuming the README branch is already the final stable workflow.
Recommended Practical Strategy
- If the user wants something working quickly: use
dtwin-epics-runbook
- If the user specifically needs SOLEIL TANGO: use this runbook and verify the private prerequisites first
Related Skills
dtwin-epics-runbook — faster current pathdtwin-host-smoke-test — validate public/core stack before TANGOdt4acc-container-troubleshooting — TANGO/container prerequisite issuesdtwin-setup — broader dtwin setup context
