exacross/opcua-gateway repository overview

⁠OPC UA Gateway

A Node.js-based gateway providing a modern REST API for secure communication with OPC UA servers. Bridge the gap between your industrial OT systems and IT applications with ease.

Source Code & Full Documentation: https://github.com/tinroad/opcua-gateway⁠

---

⁠Quick Start (Recommended: Docker Compose)

This is the fastest way to get the gateway running using the official Docker Hub image.

1. Create docker-compose.yml file: Create a file named docker-compose.yml with the following content:

   version: '3.8'
   services:
     opcua-gateway:
       image: exacross/opcua-gateway:latest # Use the image from Docker Hub
       container_name: opcua-gw
       ports:
         - "3000:3000" # Map host port to container port
       env_file:
         - .env        # Load environment variables from .env file
       restart: unless-stopped
       # Optional: Mount volume for certificates if using secure modes
       # volumes:
       #   - ./certificates:/app/certificates
   

   Copy

2. Create .env file: In the same folder, create a file named .env. Add the necessary configuration variables. At a minimum, you need:

   # Required for basic connection
   OPC_ENDPOINT=opc.tcp://YOUR_OPCUA_SERVER:4840
   
   # Required for API security (choose one or both)
   API_KEY=A_SECURE_API_KEY_HERE
   # or
   AUTH_USERNAME=your_basic_user
   AUTH_PASSWORD=your_basic_password
   
   # Recommended (adjust as needed)
   LOG_LEVEL=info
   LOG_TO_CONSOLE=true
   

   Copy

   Replace example values with your actual configuration. See the full list of variables below or in the GitHub README⁠.

3. Start the Container: Open a terminal in the folder and run:

   docker-compose up -d
   

   Copy

   Docker will pull the image and start the container.

4. Verify Status: Wait a few seconds and check the health endpoint:

   curl http://localhost:3000/health
   # Expect: {"status":"UP","opcClient":"CONNECTED",...}
   

   Copy

---

⁠Alternative Quick Start (docker run)

1. Pull the image:

   docker pull exacross/opcua-gateway:latest
   

   Copy
2. Create .env file: Create a .env file with your configuration variables as described in Step 2 of the Docker Compose method.
3. Run the container:

   docker run -d -p 3000:3000 --name opcua-gw --env-file ./path/to/your/.env exacross/opcua-gateway:latest
   

   Copy
   (Adjust the path to your .env file)

---

⁠Key Features

• 🔐 Secure Connection: Supports various OPC UA security modes and policies.
• 🚀 Modern REST API: Intuitive endpoints (/iotgateway/read, /iotgateway/write) for OPC UA interaction.
• 🤝 Kepware Compatibility: /iotgateway endpoints designed for easy integration/migration.
• 🔗 Connection Pooling: Efficient management of OPC UA sessions.
• 🔄 Automatic Reconnection: Robust handling of disconnections with configurable retries.
• 🛡️ API Security: Dual Authentication (Basic/API Key), Rate Limiting, CORS Protection, Helmet security headers.
• 📊 Advanced Monitoring: Detailed metrics via REST API and SNMP (v1/v2c/v3) support.
• ⚙️ Zabbix Integration: Includes a tool to generate a Zabbix monitoring template (npm run generate:zabbix in source).
• 📝 Configurable Logging: Control log levels and output (console/file).
• 🐳 Easy Deployment: Optimized for Docker.

---

⁠Configuration (Environment Variables)

The gateway is configured using environment variables, typically loaded from a .env file when using docker-compose or docker run --env-file.

Essential Variables:

• OPC_ENDPOINT: URL of your OPC UA server (e.g., opc.tcp://192.168.1.100:4840).
• One or both sets for API Authentication:
  • API_KEY: Secret key for X-API-Key header authentication.
  • AUTH_USERNAME / AUTH_PASSWORD: Credentials for HTTP Basic Authentication.

Key Optional/Conditional Variables:

• OPC UA Security: OPC_SECURITY_MODE, OPC_SECURITY_POLICY (Required if mode > 1: OPC_CERTIFICATE_FILE, OPC_PRIVATE_KEY_FILE, OPC_TRUSTED_FOLDER, OPC_REJECTED_FOLDER).
• Connection Tuning: CONNECTION_RETRY_MAX, CONNECTION_INITIAL_DELAY, CONNECTION_MAX_RETRY, CONNECTION_MAX_DELAY, CONNECTION_RETRY_DELAY.
• Server: SERVER_PORT (defaults to 3000).
• API Security: ALLOWED_ORIGINS, CORS_MAX_AGE, RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX.
• Logging: LOG_LEVEL, LOG_FILE_ERROR, LOG_FILE_COMBINED, LOG_TO_CONSOLE.
• SNMP: ENABLE_SNMP, SNMP_PORT, SNMP_COMMUNITY, SNMP_VERSION, and SNMPv3 credentials (SNMP_SECURITY_NAME, SNMP_SECURITY_LEVEL, etc.).

➡️ For a full list and detailed explanation of all variables, please refer to the Configuration Section in the GitHub README⁠.

---

⁠API Endpoints (Overview)

• GET /iotgateway/read?ids=<nodeId1>: Reads values from specified OPC UA nodes.
• POST /iotgateway/write: Writes values to specified OPC UA nodes (see body format in full docs).
• GET /health: Public endpoint for health status check.
• /api/...: Additional endpoints for status, metrics, and direct node interaction (require authentication).

➡️ For detailed request/response formats and all endpoints, see the API Endpoints Section in the GitHub README⁠.

---

⁠Security Highlights

• Supports secure OPC UA connections (Sign, SignAndEncrypt).
• REST API secured via Basic Authentication and/or API Key.
• Rate limiting to prevent abuse.
• CORS protection for browser-based access.
• Helmet middleware for common web vulnerability protection.

---

⁠Monitoring Highlights

• Exposes detailed metrics via REST endpoints (/api/metrics/...).
• Built-in SNMP Agent (v1, v2c, v3) for integration with standard monitoring tools.
• Includes a helper script to generate a Zabbix template for easy monitoring setup.

---

⁠Support & Contributing

• For issues, questions, or feature requests, please use the GitHub Issues⁠.
• Contributions are welcome! Please see the Contributing Guide⁠.

---

⁠License

MIT License - see LICENSE file⁠ for details.