OPC UA Light Server

Lightweight, self-hosted OPC UA server with multi-protocol PLC integration (Siemens S7, Modbus TCP, EtherNet/IP, PCCC)

OPC UA Light Server is a free, open-source, self-hosted OPC UA server for industrial IoT and SCADA systems. It bridges industrial PLCs — Siemens S7, Modbus TCP, Rockwell EtherNet/IP, and Allen-Bradley PCCC — into an OPC UA address space, then serves them over the standard OPC-UA protocol (TCP port 4840) to any OPC UA client. Built on the open62541 C runtime with a Node.js REST API and a React web dashboard, it runs anywhere Docker runs and needs zero external infrastructure.

Use it as an OPC UA gateway, a PLC-to-OPC-UA bridge, a Modbus-to-OPC-UA converter, or a lightweight OPC UA test server for development.

Check out the Getting Started section for full instructions.

1. npm install && npm install --prefix web
2. npm run build && npm run build:web
3. Build the C runtime (see Getting Started)
4. npm start

• Address Space Management — CRUD for namespaces, folders, and nodes via REST API and web UI
• Server Lifecycle — Start, stop, and hot-reload the OPC UA runtime from the dashboard
• Security Configuration — Security modes (None / Sign / SignAndEncrypt) with certificate management and TOFU client trust
• Multi-Protocol PLC Integration — Siemens S7, Modbus TCP, Rockwell EtherNet/IP, and Allen-Bradley PCCC via a plugin-based connector architecture
• Web Dashboard — Real-time server status, connector health, certificate summary, address space stats, and per-client session details
• Real-Time Updates (SSE) — Single Server-Sent Events connection replaces polling for all live data
• Authentication — API key or JWT protection on mutating endpoints
• Docker Support — Multi-stage Alpine-based image (~200 MB) for amd64 and arm64

• Getting Started
• Docker
• Configuration
• API Reference
• Architecture
• Project Structure
• Tech Stack
• Testing
• Contributing
• License

┌─────────────────┐       HTTP/REST       ┌──────────────────────────────┐
│   React Web UI  │ ◄──────────────────── │   Node.js Control API        │
│   (Vite + TW)   │                       │   Express + better-sqlite3   │
└─────────────────┘                       └──────────┬───────────────────┘
                                                     │ spawn / signal
                                                     ▼
                                          ┌──────────────────────────────┐
  OPC UA Clients ◄── TCP 4840 ──────────► │   open62541 Runtime (C)      │
                                          └──────────────────────────────┘
                                                     ▲
                                                     │ IPC (value updates)
                                          ┌──────────┴───────────────────┐
                                          │   Connector Registry         │
                                          │   S7 · Modbus TCP ·          │
  Industrial PLCs ◄── S7/Modbus/CIP ────► │   EtherNet/IP · PCCC        │
                                          │   polling + reconnection     │
                                          └──────────────────────────────┘

Key design decisions:

• The C runtime runs as a separate OS process for crash isolation
• Communication uses a JSON config file (API writes, runtime reads on start/reload) and stdin IPC for live value updates
• SQLite provides persistence with zero external infrastructure
• Global error safety nets (uncaughtException, unhandledRejection) prevent connector library crashes from taking down the API

• Node.js 18+
• CMake 3.16+ and a C11 compiler (for the open62541 runtime)
• Git (CMake FetchContent downloads open62541 and cJSON automatically)

# Install Node.js dependencies (API + web UI)
npm install
npm install --prefix web

# Copy the environment file
cp .env.example .env

# Build the Control API (TypeScript → dist/)
npm run build

# Build the Web UI
npm run build:web

# Build the OPC UA runtime
cd runtime
mkdir build && cd build
cmake ..
cmake --build .
cd ../..

npm start

The server starts on port 3100. Open http://localhost:3100 for the web UI.

# Start the API in watch mode (hot-reload on TypeScript changes)
npm run dev

# Start the web UI dev server (HMR via Vite)
cd web && npm run dev

# Run all tests
npm test

# Run specific test suites
npm run test:unit         # Unit tests
npm run test:property     # Property-based tests (fast-check)
npm run test:integration  # Integration tests

# Reset runtime data (database, certificates, PKI store)
npm run reset

Build and run as a container (includes API, web UI, and OPC UA runtime):

# Build the image
docker build -t opcua-light-server .

# Run with default settings
docker run -d -p 3100:3100 -p 4840:4840 -v opcua-data:/app/data opcua-light-server

# Run with custom environment
docker run -d \
  -p 3100:3100 \
  -p 4840:4840 \
  -e AUTH_MODE=api-key \
  -e API_KEYS=mykey \
  -v opcua-data:/app/data \
  opcua-light-server

The image uses a multi-stage build (Alpine-based, ~200 MB final size). Port 3100 serves both the REST API and the web UI. Port 4840 is the OPC UA runtime (TCP).

For multi-platform builds (amd64 + arm64):

docker buildx build --platform linux/amd64,linux/arm64 -t your-registry/opcua-light-server:latest --push .

To build an ARM image and export it as a tarball (no registry):

docker buildx build --platform linux/arm64 -t opcua-light-server:arm64 -o type=docker,dest=opcua-arm64.tar .

Then transfer and load on the ARM device:

docker load -i opcua-arm64.tar

Corporate proxies (e.g., Zscaler) intercept TLS and re-sign certificates with their own root CA. The buildx builder runs in an isolated container that does not trust this CA, causing:

tls: failed to verify certificate: x509: certificate signed by unknown authority

To fix, point the buildkit builder at your corporate root CA.

1. Locate your corporate root CA certificate (.pem or .crt) — ask your IT department or export it from your system's trust store.

2. Create a buildkitd.toml referencing the CA for Docker Hub registries (use the absolute host path; on Windows escape backslashes):

   [registry."docker.io"]
     ca=["/path/to/corporate_root_ca.pem"]
   
   [registry."registry-1.docker.io"]
     ca=["/path/to/corporate_root_ca.pem"]

3. Recreate the buildx builder with this config:

   docker buildx rm multiarch
   docker buildx create --name multiarch --driver docker-container \
     --driver-opt network=host \
     --config ./buildkitd.toml --use

4. Build as normal — buildx injects the CA into the builder container automatically:

   docker buildx build --platform linux/arm64 -t opcua-light-server:arm64 \
     -o type=docker,dest=opcua-arm64.tar .

All mutating endpoints (POST, PUT, DELETE) require authentication. GET /api/server/status is unauthenticated for health monitoring.

API Key mode:

AUTH_MODE=api-key
API_KEYS=key1,key2,key3

Header: Authorization: Bearer key1

JWT mode:

AUTH_MODE=jwt
JWT_SECRET=your-secret
JWT_ISSUER=your-issuer

Sign and SignAndEncrypt require a server certificate. Generate one via the API or web UI before enabling these modes. The runtime restarts automatically when the security mode changes.

When security is enabled, clients must present an X.509 certificate. The server uses Trust On First Use:

1. First connection — unknown certificate auto-stored in data/pki/trusted/
2. Subsequent connections — recognized by thumbprint (SHA-1)
3. Revocation — move to data/pki/rejected/ via API or web UI
4. Re-trust — move back to trusted store

Trust store changes take effect immediately via IPC — no restart required.

Interactive documentation: http://localhost:3100/api/docs (Swagger UI)

OpenAPI 3.0 spec: docs/openapi.json

Supported protocols: s7, modbus-tcp, ethernet-ip, pccc

Events: server:status, server:clients, connector:status, connector:values, log:entry

opcua-light-server/
├── src/                      # Control API (TypeScript, ES modules)
│   ├── api/                  # Express app, routes, SSE hub
│   ├── auth/                 # Authentication middleware
│   ├── cert-generator/       # Certificate generation and DER/PEM conversion
│   ├── config-generator/     # Runtime JSON config builder
│   ├── connectors/           # Multi-protocol connector plugin system
│   │   ├── core/            # Framework (BaseConnector, registry, loader, validator)
│   │   └── protocols/       # Plugins (s7, modbus-tcp, ethernet-ip, pccc)
│   ├── db/                   # SQLite database and repositories
│   ├── log/                  # In-memory log service with SSE broadcast
│   ├── process-manager/      # C runtime child process lifecycle
│   ├── tofu-manager/         # TOFU certificate trust management
│   ├── types/                # Domain types and DTOs
│   └── utils/                # Shared utilities
├── web/                      # React Web UI (Vite + Tailwind)
│   └── src/
│       ├── api/              # Typed API client
│       ├── components/       # Shared UI primitives
│       ├── hooks/            # React Query hooks, SSE, log stream
│       ├── layout/           # App shell, NavBar, StatusBar, LogPanel
│       └── screens/          # Feature screens (dashboard, connectors, security, address-space)
├── runtime/                  # open62541 C Runtime
│   └── src/                  # Server, config parser, IPC, security, status writer
├── tests/                    # Unit, property, integration, component tests
├── docs/                     # OpenAPI spec, error recovery audit
└── data/                     # Runtime data (database, certificates, PKI)

• Node.js 18+ + Express 4 — Control API
• TypeScript 5 — strict mode, ES modules
• better-sqlite3 — embedded database
• open62541 v1.3.9 — OPC UA C runtime (via CMake FetchContent)
• React 18 + TanStack React Query — web UI
• Tailwind CSS — styling (centralized class maps)
• Vite — frontend build
• Vitest + fast-check — testing (unit, property, integration, component)
• nodes7 / modbus-serial / ethernet-ip / nodepccc — PLC protocol libraries
• node-forge — certificate generation
• Docker — multi-stage Alpine build

npm test                  # Run all (unit + property + integration + component)
npm run test:unit         # Unit tests only
npm run test:property     # Property-based tests (fast-check)
npm run test:integration  # Integration tests (requires runtime binary)

Boolean, Int16, Int32, Int64, UInt16, UInt32, UInt64, Float, Double, String, DateTime, ByteString

This project follows Conventional Commits:

type(scope): short imperative description

Types: feat, fix, refactor, test, docs, chore, style, perf

Scopes: web, api, security, dashboard, runtime, db, nodes

MIT — see LICENSE.