Skip to content

Getting started

github-actions[bot] edited this page Nov 17, 2026 · 5 revisions

Getting started

Easiest way

Open Claude Code in the repository folder and run this prompt:

read the CLAUDE.md file and README.md file and set up the environment

Prerequisites

  • Docker Desktop (or Docker Engine + Compose v2)
  • Free host ports: 8110 (DCS console), 8111 (instructor station), 4840 (OPC UA), 5020 (Modbus TCP), 1880 (Node-RED); for the two other sites also 8120, 8121, 4841, 5021 (Port Arden) and 8130, 8131, 4842, 5022 (Vadhana)

Start

git clone https://github.com/itotinsider/haltenberg-chemische-werke-uns.git
cd haltenberg-chemische-werke-uns
docker compose up -d --build

Then open the hub at http://localhost:8110. The plant starts at steady state; it doesn't need a start-up procedure.

On a Linux host (or WSL2 with the repository on the Linux file system) the DCS containers run as user nobody (uid 65534) and must be able to write their data folders, data/ (Haltenberg), data/port-arden/ and data/vadhana/. These folders come with the repository, but they belong to you, so allow the DCS to write them once:

chmod a+rwx data data/port-arden data/vadhana

Docker Desktop on macOS and Windows doesn't need this. If a DCS container stops at start-up with "Cannot write the data folder" (older versions: sqlite3.OperationalError: unable to open database file), this is the cause. A folder that was missing when the stack started was created by Docker as root; then docker compose down, sudo chown -R $USER data, the chmod above, and start again.

What Where
Hub (all systems) http://localhost:8110
DCS operator console http://localhost:8110/operator
Historian trends http://localhost:8110/operator#trends
Detail display (e.g. the columns) http://localhost:8110/operator#detail/C-401
Trainers (overlays on the console) http://localhost:8110/operator?training=ot (IT/OT), training=eng, training=1
Instructor station (fault scenarios) http://localhost:8111
OPC UA endpoint opc.tcp://localhost:4840/hcw/asu1/ (anonymous, no security)
Modbus TCP field I/O (raw) localhost:5020, unit 1
Node-RED (OPC UA client flows) http://localhost:1880
15-min averages (CSV, written by Node-RED) exports/asu1_twa_15min.csv
Port Arden (US) hub · OPC UA http://localhost:8120 · opc.tcp://localhost:4841/PortArden/ASU7100
Vadhana (IN) hub · OPC UA http://localhost:8130 · opc.tcp://localhost:4842/vadhana/asu2

The other two sites are described in Global sites.

Hub — one page linking every system, grouped by ISA-95 level.

Hub

A first tour (15 minutes)

New to plants? Read Plant automation in brief first.

  1. Open the hub at http://localhost:8110 and go to the DCS operator console.
  2. Switch on 🎓 Training and step through the process with ▶. Want more depth? Each step has "Go deeper" buttons, and the switch at the top of the card changes to the Engineering and IT/OT trainers without leaving the console.
  3. Click the value of FIC-101 (the air flow) to open its faceplate: PV, SP, OP, mode and a trend.
  4. Click the column on the overview to open the C-401 detail display. Back and Close take you back.
  5. Open the instructor station (http://localhost:8111) and start GAN compressor K-503 motor trip.
  6. Back in the console, watch the Alarms tab (I-503.TRIP), and in Trends the nitrogen header PIC-504 dip while the LIN backup FIC-508 takes over.
  7. Recover: on the Interlocks tab reset I-503, start the GAN compressor and, once it runs, press Normal line-up. FIC-508 winds down as K-503 takes the header back.

Stop / reset

docker compose down              # stop
rm data/historian.db* data/dcs_state.json   # wipe history and controller state (Haltenberg)
rm data/*/historian.db* data/*/dcs_state.json   # ... and of the other two sites (keep the folders)
rm exports/*.csv                            # wipe the Node-RED averages

After pulling a change to dcs/config.py (controller tuning, SP limits), remove or rename data/dcs_state.json before docker compose up -d --build. The checkpoint restores each loop's tuning and limits, so otherwise the DCS keeps the old values.

After a change to the Modbus map (common/iomap.py), stop the stack first with docker compose down, and only then docker compose up -d --build. Also move the checkpoint aside. Otherwise the old DCS runs against the new plant for a few seconds and reads the wrong registers. That's like a real I/O-map mismatch: run feedbacks look lost, the DCS trips the machines, and the checkpoint saves those trips.

Clone this wiki locally