Docker Lab Walkthrough

This walkthrough stands up docker-industrial-lab — a local OPC UA + MQTT simulator sandbox that ships in this repository — next to your Xisom stack, so you can exercise the MQTT and OPC UA datasource adapters end-to-end without a real plant network.

Where this lives

The lab is part of this repository at docker-industrial-lab/ — it is not a separate repo to clone. It has its own docker-compose.yml, a generated .env, and a Makefile with up / down / smoke targets.

What you’ll build

• OPC UA simulator (lab-opcua) — a secured server exposing factory tags, writable setpoints (for testing AIBOARD output writes), and scale-testing sample tags.
• MQTT broker (lab-mosquitto, Eclipse Mosquitto) — secured by default (TLS + username/password, or mutual-TLS), with an anonymous fallback profile.
• MQTT publisher + sniffer — simulate a device publishing factory data, and confirm what AIBOARD’s output sink actually writes.
• Your Xisom stack (inference + backend + frontend) — attached to the lab’s Docker network via the opt-in docker-compose.lab.yml overlay at the repo root, or reached over host loopback without it.

Steps

1. Bootstrap secrets and bring the lab up. The stack is secured by default; a one-shot script mints a private CA, client certs, and broker/OPC UA credentials on first run:

   cd docker-industrial-lab
   ./scripts/bootstrap-secrets.sh   # or: make certs
   docker compose up -d             # or: make up
   docker compose ps                # expect every service "healthy" within ~30s

   Don't hand-copy .env.example

   bootstrap-secrets.sh generates the real .env (random passwords + COMPOSE_PROFILES=secure). Copying .env.example to .env yourself skips the PKI mint — the certs-guard service then fails fast until you run the script.

2. Run the smoke test to confirm the secured stack end-to-end:

   ./scripts/smoke-test.sh   # or: make smoke

3. Attach your Xisom stack to the lab network (from the repo root, one level up):

   cd ..
   docker compose -f docker-compose.yml -f docker-compose.lab.yml up -d

   This attaches the backend service to the lab’s industrial-lab Docker network so it reaches the simulators by container DNS (opcua, mosquitto) — no host ports needed. Host-loopback URLs (host.docker.internal:...) also work without this overlay.

4. Add the datasources in the Xisom dashboard — an OPC UA input at opc.tcp://opcua:4840/factory/line1 (or host.docker.internal without the overlay), and/or an MQTT input at mqtt://mosquitto:8884 (TLS + username/password). Credentials are in the generated docker-industrial-lab/.env.

Verify

• docker compose ps (inside docker-industrial-lab/) shows every service healthy.
• In the Xisom dashboard, enable and Start the datasource, then open Inference Stats — you should see live throughput from the simulated tags.
• Confirm what an AIBOARD output write actually lands as: docker logs lab-opcua | grep WRITE or docker logs lab-mqtt-sniffer.

Sample env knobs (load/scale testing)

(v1.28.0, lab-only — no effect on the product runtime.) Both simulators expose extra env knobs in docker-industrial-lab/.env for driving higher tag counts and rates than the default factory demo, useful for exercising AIBOARD’s adapter under load:

Env var	Default	Purpose
SAMPLE_TAG_COUNT	100	Extra sample tags on both protocols — MQTT aiboard/sample_mqtt/topic_1..N, OPC UA ns=2;s=SampleOpcua_Tag_1..N. 0 disables.
SAMPLE_RATE_HZ	unset (historical rate)	Whole-loop sampling rate in Hz for both simulators, e.g. 10/20/50. Overrides PUBLISH_INTERVAL (MQTT) and the 1 Hz OPC UA default.
SAMPLE_WALK_STEP	4.0	Gaussian step size per sample of the mean-reverting random walk (bigger = jumpier).
SAMPLE_WALK_CENTER	50.0	Value the walk reverts toward.
SAMPLE_WALK_REVERSION	0.05	Pull strength toward the centre, 0–1 (0 = pure random walk).
SAMPLE_MQTT_QOS	0	QoS for sample MQTT topics only — test the adapter at 0/1/2. Factory topics always stay QoS 0.
SAMPLE_MQTT_RETAIN	false	Retain flag for sample MQTT topics only.

Tip

At high SAMPLE_RATE_HZ combined with a large SAMPLE_TAG_COUNT (e.g. 50 Hz × 100 tags ≈ 5k writes/s per protocol), a simulator loop can exceed its budget and the effective rate drops below target — lower one knob if you need a hard throughput guarantee.

Tear down

cd docker-industrial-lab
make down   # docker compose --profile secure --profile insecure --profile dashboard down -v

This removes containers and volumes but keeps the minted PKI (certs/, mosquitto/secrets/) so a future up doesn’t need to re-bootstrap. Rotate credentials with ./scripts/bootstrap-secrets.sh --force.

If something goes wrong

Services not reaching healthy, or no traffic in the dashboard — see the Troubleshooting runbook, and specifically MQTT input stops or faults for broker-side causes.