gcorbaz/opcgw repository overview

⁠opcgw — ChirpStack to OPC UA Gateway

opcgw is a Rust application that bridges a ChirpStack⁠ LoRaWAN Network Server to OPC UA clients for industrial automation and SCADA systems. It polls device metrics from ChirpStack's gRPC API at configurable intervals, persists them to SQLite with a 7-day rolling history, and exposes them as OPC UA variables with real-time Read, HistoryRead, and live subscription support.

The image is published in lockstep to two registries:

• Docker Hub (primary): docker.io/gcorbaz/opcgw
• GHCR (mirror): ghcr.io/guycorbaz/opcgw

Both registries receive identical multi-architecture manifests built from the same workflow run.

⁠Why opcgw vs. ChirpStack's built-in integrations?

ChirpStack ships with MQTT and HTTP integrations that already deliver device data to external systems — so why a dedicated gateway?

opcgw is a name-translation layer. Bare ChirpStack integrations emit events keyed by UUIDs (application_id, tenant_id) and DevEUIs. Downstream SCADA operators see opaque identifiers and have no way to map 52f14cd4-c6f1-4fbd-8f87-4025e1d49242 / a840414bf185f365 to "the temperature sensor in the storeroom."

opcgw polls ChirpStack for both the configuration (tenant / application / device names) and the data (metric values), then exposes the result via OPC UA — the de-facto standard for industrial automation — with a named browse tree that operators can read directly:

Server
└── Objects
    └── Bâtiments                ← your application_name (any Unicode)
        └── lsn50-magasin        ← your device_name
            ├── Humidity         ← Float, 72.36
            ├── Temperature      ← Float, 15.13 °C
            └── BatV             ← Float, 3.67

If you're already running OPC UA SCADA software (Ignition, KEPServerEX, B&R, Siemens, etc.), opcgw plugs straight into it — no custom MQTT-to-tag glue code, no UUID translation table to maintain.

⁠Architecture

LoRaWAN device                                            OPC UA client
(uplinks ~every                                           (SCADA / HMI /
20 minutes)                                                historian)
       │                                                          ▲
       ▼                                                          │
 ┌──────────────┐    gRPC      ┌────────────────────┐  OPC UA TCP │
 │  ChirpStack  │◄─── poll ────│       opcgw        │─────────────┘
 │  v4 server   │  every 60s   │  • Name translation│  (port 4840)
 │              │              │  • SQLite history  │
 └──────────────┘              │  • Optional web UI │  HTTP(S)
                               └────────────────────┘─────────────┐
                                                                  ▼
                                                          Operator browser
                                                          (port 8080)

⁠Features

⁠OPC UA server (port 4840)

• Read — current value of any configured metric, with timestamp + quality
• HistoryRead — time-series reads over the last 7 days (configurable retention)
• Subscriptions / MonitoredItems — push-based updates to clients on metric change
• Standard data types — Float, Int32/Int64, Boolean, String
• Anonymous + username/password security profiles (None security policy out of the box; PKI-validated profiles supported)
• Session-count + connection-limit telemetry — opcgw caps concurrent sessions per [opcua].max_connections and emits a opcua_session_count_at_limit warn when the limit is reached

⁠Embedded web UI (port 8080 — enabled by default; toggle via OPCGW_WEB__ENABLED)

• Zero-touch first-run setup wizard — on first boot, collects the ChirpStack connection (server address, tenant ID, API token) and the OPC UA password from the browser; secrets are written to config/secrets.toml (mode 0600) and the rest to SQLite — no text-file editing required to stand up a fresh gateway
• Live metrics dashboard — current value + last-uplink timestamp for every configured metric, auto-refreshing
• Application / Device / Metric CRUD with ChirpStack inventory pickers — build the topology by selecting applications/devices/metrics from your live ChirpStack inventory by name; changes stage to SQLite and apply together via an explicit "Apply changes" soft restart (see below)
• Inventory drift view — diff your configured inventory against ChirpStack and reconcile from the UI
• ChirpStack status tile — last poll outcome, cumulative error count, gateway uptime
• Commands page — downlink command queue + delivery-status tracking
• HTTP basic-auth gating — single set of credentials shared with the OPC UA server (no separate web account to manage)

⁠Gateway operations

• Configurable poll cadence — polling_frequency per ChirpStack, default 60s
• Failure-isolating per-device polling — a single failing device cannot stop the cycle for the rest
• Auto-recovery loop — opcgw retries ChirpStack connection on transient outages with configurable backoff
• Staged configuration editor with explicit "Apply changes" — edit the [global] / [chirpstack] / [opcua] / [web] settings from the web UI; edits accumulate as pending changes (GET /api/status reports pending_changes: true) and apply together via one POST /api/config/apply in-process soft restart of the data plane — the container is never restarted, so OPC UA clients aren't dropped on every individual save
• Config export / import — download the full configuration as portable TOML (secrets excluded) and restore it on another instance through the staged-apply flow
• Structured JSON logs — every operationally-meaningful event is emitted at info or higher with a closed-enum event= taxonomy suitable for SIEM / log aggregation

⁠Persistence

• SQLite with WAL mode — concurrent read/write, crash-safe
• 7-day metric history (configurable via [opcua].history_retention_days) — auto-pruned by background task
• Atomic schema migrations — versioned (v001–v013), per-startup forward-only

⁠Who is this for?

⁠Supported architectures

• linux/amd64 — x86_64 servers, VMs, industrial PCs
• linux/arm64 — Raspberry Pi 4/5, AWS Graviton, Apple Silicon dev workstations

32-bit ARM (linux/arm/v7) is not currently published.

⁠Supported tags

Tags follow Semantic Versioning⁠ and are generated by docker/metadata-action@v5 from the git tag that triggered the build:

For reproducible production deployments, pin to a specific minor (:2.5) or patch (:2.5.0) rather than :latest.

⁠Quick start

⁠docker run

docker run -d \
  --name opcgw \
  --restart unless-stopped \
  -p 4840:4840 \
  -e OPCGW_CHIRPSTACK__API_TOKEN='<your-chirpstack-api-token>' \
  -e OPCGW_OPCUA__USER_PASSWORD='<your-opc-ua-user-password>' \
  -v "$(pwd)/config:/usr/local/bin/config" \
  -v "$(pwd)/pki:/usr/local/bin/pki" \
  -v "$(pwd)/log:/usr/local/bin/log" \
  -v "$(pwd)/data:/usr/local/bin/data" \
  gcorbaz/opcgw:2.5

⁠docker compose

Use the bundled docker-compose.yml and .env.example from the GitHub repository — see the Quick start in the user manual⁠ for the canonical recipe.

git clone https://github.com/guycorbaz/opcgw.git
cd opcgw
cp .env.example .env
# Edit .env to set OPCGW_CHIRPSTACK__API_TOKEN + OPCGW_OPCUA__USER_PASSWORD
docker compose up -d

⁠Environment variables

opcgw stores its configuration in SQLite, seeded once from config/config.toml on first boot, and accepts environment-variable overrides following the OPCGW_<SECTION>__<FIELD> pattern (double underscore separates the section from the field; figment-driven). Precedence: env var > SQLite > config.toml > default.

The most commonly overridden values:

The :?err shell guard in docker-compose.yml causes Compose parsing to fail fast if required env-vars are unset or empty — see the security guide. Note: :?err does not detect literal placeholder strings (e.g. REPLACE_ME_WITH_…); operators who copy .env.example verbatim without filling the values get a container that starts successfully and then errors at gateway startup. Replace every placeholder before docker compose up.

⁠Exposed ports

• 4840 — OPC UA endpoint (opc.tcp://). Configurable via [opcua].host_ip_address (default 0.0.0.0) + [opcua].host_port (default 4840) in config.toml.
• 8080 — Embedded Axum web UI. Enabled by default in the shipped config.toml (toggle via [web].enabled / OPCGW_WEB__ENABLED; configurable via [web].port). Publish with -p 8080:8080 on docker run to expose it on the host.

⁠Quick-start variant: with the Web UI

docker run -d \
  --name opcgw \
  --restart unless-stopped \
  -p 4840:4840 \
  -p 8080:8080 \
  -e OPCGW_CHIRPSTACK__API_TOKEN='<your-chirpstack-api-token>' \
  -e OPCGW_OPCUA__USER_PASSWORD='<shared-opcua-and-web-password>' \
  -e OPCGW_WEB__ENABLED=true \
  -v "$(pwd)/config:/usr/local/bin/config" \
  -v "$(pwd)/pki:/usr/local/bin/pki" \
  -v "$(pwd)/log:/usr/local/bin/log" \
  -v "$(pwd)/data:/usr/local/bin/data" \
  gcorbaz/opcgw:2.5

The web UI shares OPC UA credentials (single source of truth — OPCGW_OPCUA__USER_NAME + OPCGW_OPCUA__USER_PASSWORD). Place it behind a TLS-terminating reverse proxy in production deployments.

⁠Volume mounts

The container's WORKDIR is /usr/local/bin. Standard bind-mount layout:

⁠Non-root operation

opcgw runs as user opcgw (UID 10001), NOT root. Bind-mounted host directories must be readable / writable by UID 10001:

# One-time host-side ownership fix before first start:
sudo mkdir -p ./config ./pki/{own,private,trusted,rejected} ./log ./data
sudo chown -R 10001:10001 ./config ./pki ./log ./data
sudo chmod 700 ./pki/private    # NFR9 - OPC UA private key parent dir
# Tighten any pre-existing private key files (no-op on a fresh install):
sudo find ./pki/private -type f -name '*.pem' -exec chmod 600 {} +

⁠Configuration

On first boot the container reads config/config.toml from the bind-mounted config directory to seed its SQLite database; after that, configure the gateway from the web UI. A complete example with field-by-field documentation lives in the user manual⁠. The minimal bootstrap sections are [chirpstack] and [opcua]; applications/devices are most easily added through the web UI pickers (or seeded via [[application]] → [[application.device]] → [[application.device.read_metric]] sub-tables).

⁠Health check / verification

After docker compose up -d (or docker run), verify the gateway is running correctly:

# Process runs as UID 10001 (not root)
docker exec opcgw id

# OPC UA endpoint is bound on port 4840
nc -z localhost 4840 && echo "OPC UA endpoint reachable"

# Tail logs to watch the first ChirpStack poll cycle
docker logs -f opcgw

Look for the structured-log event operation="poll_cycle_start" within ~30 seconds of startup, followed by operation="poll_cycle_end" on each successful cycle. When [opcua].diagnostics_enabled = true is set, the periodic event="opcua_session_count" gauge (fired every ~5 s) additionally confirms the OPC UA server is listening; with diagnostics disabled the gauge does not fire, so use event="opcua_limits_configured" from startup as the alternative listener-up signal.

⁠Troubleshooting

For anything else, file an issue at https://github.com/guycorbaz/opcgw/issues⁠.

⁠Scale & performance

Indicative numbers from a Raspberry Pi 4 / 8 GB running opcgw against a local ChirpStack v4.x:

⁠Upgrading from v2.0-rc

Use the migration runbook⁠ at docs/deployment-guide.md § "Epic A migration". The repository ships scripts/check-schema-version.sh⁠ as a pre-flight tool that inspects an existing SQLite file and recommends Path A (in-place upgrade) or Path B (drop-and-recreate). Migration is one-way; restoring from a pre-upgrade backup is the only rollback.

⁠Links

• Source code: https://github.com/guycorbaz/opcgw⁠
• Full user manual: https://github.com/guycorbaz/opcgw/blob/main/docs/manual/opcgw-user-manual.xml⁠ (DocBook 4.5 XML; build to HTML/PDF via docs/manual/Makefile)
• Deployment guide: https://github.com/guycorbaz/opcgw/blob/main/docs/deployment-guide.md⁠
• Security guide: https://github.com/guycorbaz/opcgw/blob/main/docs/security.md⁠
• Changelog: https://github.com/guycorbaz/opcgw/blob/main/CHANGELOG.md⁠
• GHCR mirror: https://github.com/guycorbaz/opcgw/pkgs/container/opcgw⁠
• Issue tracker: https://github.com/guycorbaz/opcgw/issues⁠

⁠License

Dual-licensed under either:

• MIT License — https://github.com/guycorbaz/opcgw/blob/main/LICENSE-MIT⁠
• Apache License 2.0 — https://github.com/guycorbaz/opcgw/blob/main/LICENSE-APACHE⁠

at your option.