Setting up OPC Router with LocalStack (ECS)

LocalStack replicates AWS services locally. This scenario is intended to allow you to test an AWS ECS deployment of the OPC Router on your own computer before deploying it to a live AWS environment—it is explicitly not intended for production use.

This guide describes how to run the OPC Router as a containerized application using AWS ECS on LocalStack. We’ll use Docker containers, LocalStack (with ECS and ECR support), and the AWS/awslocal CLI. Key components of this configuration (ports, volumes, environment variables, etc.) are based on the sample task definition provided below.

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: Load 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 LOCALSTACK_AUTH_TOKEN=<your-auth-token> \
    -v /var/run/docker.sock:/var/run/docker.sock \
    localstack/localstack-pro

This command sets the auth token from your cloud account and mounts the Docker socket into the container; the socket mount is required for ECS emulation because LocalStack launches the task containers via the host’s Docker daemon.

note

When using an auth token, you must use the localstack/localstack-pro image. The services are intentionally not restricted to SERVICES here—this guide requires ECS and ECR.

Prepare the task definition (JSON): Save an ECS task definition as a JSON file in the working directory, for example, as OPC_Router_localstack.json. It defines the OPC Router container, its CPU and memory requirements, the port mapping, and the persistence volumes:

OPC_Router_localstack.json

{
  "family": "opcrouter-primary",
  "networkMode": "bridge",
  "containerDefinitions": [
    {
      "name": "opcrouter-primary",
      "image": "opcrouter/runtime:latest",
      "cpu": 3072,
      "memory": 5120,
      "essential": true,
      "hostname": "opc-router-cluster",
      "environment": [
        { "name": "OR_I_ACCEPT_EULA", "value": "true" },
        { "name": "TZ", "value": "Europe/Berlin" },
        { "name": "INITIAL_USERNAME", "value": "<username>" },
        { "name": "INITIAL_PASSWORD", "value": "<password>" },
        { "name": "OR_WEB_DISABLE_HTTPS", "value": "true" }
      ],
      "portMappings": [
        {
          "containerPort": 8080,
          "hostPort": 8081,
          "protocol": "tcp"
        }
      ],
      "mountPoints": [
        { "containerPath": "/data", "sourceVolume": "opc-router-data" },
        { "containerPath": "/var/log/opcrouter", "sourceVolume": "opc-router-logs" }
      ],
      "logConfiguration": { "logDriver": "json-file" }
    }
  ],
  "volumes": [
    { "name": "opc-router-data", "host": { "sourcePath": "/opt/opc-router-data" } },
    { "name": "opc-router-logs", "host": { "sourcePath": "/opt/opc-router-logs" } }
  ],
  "requiresCompatibilities": ["EC2"],
  "cpu": "3072",
  "memory": "5120",
  "runtimePlatform": {
    "cpuArchitecture": "X86_64",
    "operatingSystemFamily": "LINUX"
  }
}

The port mapping exposes the container port 8080 (Web Management) as the host port 8081. The two volumes map the host paths /opt/opc-router-data and /opt/opc-router-logs to the mount paths /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 will now appear 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 verify that the definition exists.

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. Verify 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.