UA-.NETStandard/docs/ContainerReferenceServer.md

Container support and remote debugging for Reference Server

Overview

Run the Reference Server in a Docker container using a published image or a local build:

• Pull the latest or a release image from the GitHub Container Registry. These images support Linux targets.
• The image supports amd64 and arm64. The sample builds inside a container, so you do not need to install the .NET SDK. This change was introduced in this commit.
• Build locally with Docker Desktop on Linux or Windows. Docker Desktop settings select the target container OS.
• Visual Studio 2019 and later include container support, but issues in the UA Reference solution currently prevent build, startup, or connection.
• Visual Studio 2022 supports native debugging of a Linux distribution through WSL.

Contents

• Overview
• Other published sample images
• Building the local containers
• Run the reference server container
  • Run the local build of the Docker container
  • Run the prebuilt Docker container hosted on GitHub
• Known limitations and issues

Other published sample images

The Images CI workflow builds and publishes the sample images below to the GitHub Container Registry (ghcr.io/opcfoundation/uanetstandard/<image>). It builds each image for linux/amd64 and linux/arm64.

Image	Sample application
refserver	samples/Reference/ConsoleReferenceServer
ldsserver	samples/Lds/ConsoleLdsServer
boilerserver	samples/MinimalApi/MinimalBoilerServer
calcserver	samples/MinimalApi/MinimalCalcServer
mcpserver	tools/Opc.Ua.Mcp
redundantserver	samples/Redundancy/RedundantServer
redundantclient	samples/Redundancy/RedundantClient
redundantpubsub	samples/Redundancy/RedundantPubSub
pubsubclient	samples/PubSub/ConsoleReferencePubSubClient
pumpserver	samples/DI/PumpDeviceIntegrationServer

The workflow does not compile anything under emulation. Its publish-samples job publishes every sample above once, natively, as framework-dependent portable IL (no runtime identifier and no app host). The same output then runs on both platforms. Each build-and-push-image leg downloads that output and builds its Dockerfile with --build-arg PUBLISH_SOURCE=prebuilt --build-arg PUBLISH_DIR=<folder>. That build only copies files onto the platform's .NET runtime base image, so QEMU is not needed.

All sample Dockerfiles use the .NET 10 Azure Linux 3 SDK image for building and an Azure Linux 3 distroless-extra runtime or ASP.NET image for the final image. The distroless-extra variant retains ICU and time-zone data for globalization. Pump and ModelManagementServer prepare writable directories and the OpenSSL configuration in a regular Azure Linux layout stage before copying them into their distroless final images.

A local docker build without these arguments compiles from source in the Dockerfile's build stage. That stage is pinned to $BUILDPLATFORM, so a multi-platform docker buildx build --platform linux/amd64,linux/arm64 also compiles natively.

Image tags follow the release-branch-only publication model:

• Stable tags include <image>:latest, <image>:release, and version tags such as <major>.<minor> and <major>.<minor>.<patch>. Update them only from a stable commit on a canonical release/<major>.<minor> branch (see Release process). A preview build (-preview.N) does not move these tags.
• <image>:latest-<branch> (for example refserver:latest-master) tracks the most recent development build on that branch. Images CI builds these from master and from release/* branches while they are pre-release.
• <image>:<version> (for example refserver:2.0.0-preview.6 or refserver:2.0.0) identifies the exact package version used to build the image, on any branch.

For example, pull the most recently approved stable Lds server image with:

docker pull ghcr.io/opcfoundation/uanetstandard/ldsserver:latest

Pull the most recent development build with:

docker pull ghcr.io/opcfoundation/uanetstandard/ldsserver:latest-master

Each application folder contains a Dockerfile. Build it from the repository root so the build can use the repository as context, for example:

docker build -f samples/Lds/ConsoleLdsServer/Dockerfile -t opcua-lds-server .

Building the local containers

1. Open a command prompt which can execute docker commands.
2. Navigate to the folder samples/Reference/ConsoleReferenceServer.
3. Build the docker container by executing the command dockerbuild.cmd.

On Linux,

1. Open a shell which can execute docker commands.
2. Navigate to the folder samples/Reference/ConsoleReferenceServer.
3. Build the docker container by executing the command ./dockerbuild.sh.

Run the reference server container

Run the container in interactive mode with the host's hostname. The certificate store, log output, and configuration file (when you use -s) are mounted in ./OPC Foundation.

The container uses these paths by default:

• Certificate store: ./OPC Foundation/pki
• Log file: ./OPC Foundation/Logs
• Shadow configuration: ./OPC Foundation/Quickstarts.ReferenceServer.Config.xml

With -s, the container first copies the configuration file to the mounted folder. On later restarts, the server reads this copy, so you can change the settings there.

Run the local build of the Docker container

To run the local containers, batch files are provided called dockerrun.bat for Windows and dockerrun.sh for Linux.

Run the prebuilt Docker container hosted on GitHub

On Windows, open a command prompt and execute the following commands:

docker pull ghcr.io/opcfoundation/uanetstandard/refserver:latest
docker run -it -p 62541:62541 -h %COMPUTERNAME% -v "%CD%/OPC Foundation:/root/.local/share/OPC Foundation" ghcr.io/opcfoundation/uanetstandard/refserver:latest -c -s

On Linux, execute the following commands in a shell:

sudo docker pull ghcr.io/opcfoundation/uanetstandard/refserver:latest
sudo docker run -it -p 62541:62541 -h $HOSTNAME -v "$(pwd)/OPC Foundation:/root/.local/share/OPC Foundation" ghcr.io/opcfoundation/uanetstandard/refserver:latest -c -s

Known limitations and issues

• VS integrated docker build/debug support is not working with the Solution.