Skip to main content
Version: 5.5

Setting up OPC Router with LocalStack (ECS)

This section describes how to run OPC Router in a containerized environment with AWS ECS under LocalStack. We use Docker containers, LocalStack (with ECS and ECR support), and the AWS/awslocal CLI. Important parts of this configuration (ports, volumes, environment variables, etc.) are based on a sample task definition (see attached JSON file).

Prerequisites: Ensure that Docker Desktop is installed and active on your local machine. LocalStack requires a working Docker installation. Also install the AWS CLI and, if necessary, the LocalStack CLI.

LocalStack cloud account & auth token: Create a free account at app.localstack.cloud.

In your account settings, generate an auth token, provided you have the appropriate license. This auth token is required locally so that the container can activate the cloud functions (e.g., ECS). Set the token in your shell environment or via a configuration file. The auth token can also be specified directly during the following Docker run.

Start LocalStack container: Download the official LocalStack Docker image and start it with your auth token from the LocalStack cloud account.

docker run -d --name localstack-pro -p 4566:4566 -e SERVICES=s3 -e <AUTH_TOKEN> localstack/localstack-pro

This binds the Docker socket to the container (required for ECS emulation) and sets the auth token (from your cloud account). Important: When using an auth token, the image localstack/localstack-pro must be used

Prepare task definition (JSON): Save an ECS task definition as a JSON file (e.g. OPC_Router_localstack.json) in the working directory. This file defines, among other things, the OPC Router container (opcrouter/runtime:latest), CPU/memory requirements, port mappings, and persistence volumes. Example contents from the file:

  • family: mml-awz-ort-OpcRouterPrimary – Name of the task family.

  • containerDefinitions.image: opcrouter/runtime:latest.

  • environment: Important variables such as OR_I_ACCEPT_EULA=true (license acceptance), INITIAL_USERNAME, INITIAL_PASSWORD (admin access), etc. must be set here.

  • portMappings: Container port 8080 → Host port 8081 (OPC Router web UI).

  • volumes: Binds host paths /opt/opc-router-data and /opt/opc-router-logs to the container (/data and /var/log/opcrouter, respectively).

Ensure that the host directories specified in the JSON exist and are writable.

Register task definition: Register the task definition with LocalStack. Example:

aws --endpoint-url=http://localhost:4566 ecs register-task-definition --cli-input-json file://./ OPC_Router_localstack.json

This now appears in the LocalStack web interface under Resource Browser → ECS → Task Definitions. Locally, you can use aws --endpoint-url=http://localhost:4566 ecs list-task-definitions to check that the definition is present.

Create service: Now create the ECS service that starts the OPC router container based on the task definition. This can be done via the LocalStack web UI: Under Resource Browser → ECS → Clusters → (your cluster, e.g., Default) → Services → Create Service, enter a service name, select the task definition you just registered, set Desired Count to 1, and confirm.

After execution, the service becomes active and LocalStack creates a Docker container according to the definition.

Verification: After creating the service, a new Docker container should be running. Check this in Docker Desktop or via shell (docker ps). You should see a container with the image opcrouter/runtime:latest running.

Additional notes:

  • Environment variables: Be sure to set OR_I_ACCEPT_EULA=true in the json file, otherwise the container will not start. Also set INITIAL_USERNAME and INITIAL_PASSWORD.

  • Volumes: Check that /opt/opc-router-data and /opt/opc-router-logs exist on the host if they are mounted in the task definition.

  • Docker Desktop: After starting via LocalStack, the container appears in Docker Desktop (see also logs and status there).

With these steps, the OPC Router is set up in your local LocalStack ECS environment and can be used as usual at http://localhost:8081 or any other port you have configured.