Appliance

The appliance is one machine in the plant network that serves four services behind a single secured HTTPS address. These are the HMI, the project repository, the signal history and the CONNECT gateway. It needs no internet, cloud account or external DNS. Install it once on a dedicated machine. Any panel PC, tablet or office workstation in the same network can then access all four through one hostname and login.

The other deployment options serve static files to a browser. The appliance also runs containers, keeps a database and holds a git repository. You must operate these services, so this page focuses on those responsibilities.

What sits behind the address

A single reverse proxy is the only ingress. One TLS configuration, one login, and for the browser everything is same-origin.

Address	What answers	Where it runs
`/`	The HMI — realvirtual	Static files from the active release
`/appliance/`	Service dashboard, four status tiles	Static, no backend
`/connect/*`	realvirtual CONNECT gateway	Natively on the host, not in a container
`/git/*`	Forgejo — project repository and long-term archive	Container
`/influx/health`, `/influx/api/v2/*`	InfluxDB health and API	Container
`https://influx.<host>/`	The InfluxDB operating interface	Container, own subdomain

CONNECT runs outside the containers to retain fieldbus access, UDP broadcast discovery and, on Windows, its tray and self-update. Running it in a container would lose these features without adding a benefit.

The InfluxDB interface needs its own subdomain

Every route above is same-origin except one. The InfluxDB 2 operating interface does not support a subpath. It ships <base href="/"> and requests its bundle at the origin root, where the HMI answers with HTML instead. InfluxDB has no base-path option to fix this. Health checks do not reveal the failure; the interface stays blank.

It therefore lives on influx.<host>, a subdomain of its own. The health and API routes under /influx/ are unaffected and stay same-origin.

Two topologies

The installer uses scripts rather than an .exe or an MSI. You can audit the scripts, and both topologies use the same Linux code path.

Windows with CONNECT native

The standard form: one Windows box. CONNECT runs natively on Windows, at the OT network, with its tray and its self-update. Everything else — proxy, repository, history — runs as Docker containers inside a WSL2 distribution. Docker Engine, not Docker Desktop, so no Docker licence question arises at your site.

Two scheduled tasks start the distribution and CONNECT at system start, so the appliance comes up after a power cut without anyone logging in.

Linux with systemd

On Linux, CONNECT runs as a hardened systemd unit alongside the containers on the same host. There are no WSL-specific networking modes, Hyper-V firewall or changing VM address to manage.

Both topologies restrict the gateway port to the loopback address and the host’s own address. Never to the local subnet, never to any address.

Windows 11 22H2 or newer

The appliance requires Windows 11 version 22H2 or newer, build 22621 or higher.

The appliance needs mirrored networking mode in WSL2. Without it, a container cannot reach the gateway on the host. In NAT mode, the Hyper-V firewall blocks the path, and no Defender rule opens it. Testing confirmed this limitation. Windows 10 and older Windows 11 builds are unsupported. Use a different machine or the Linux topology.

You can check in a normal PowerShell before you plan anything:

(Get-CimInstance Win32_OperatingSystem).BuildNumber       # must be >= 22621
(Get-CimInstance Win32_ComputerSystem).HypervisorPresent  # must be True

The installer refuses to run on a system that is not clean

The appliance installs on a dedicated machine. If the installer finds any of the following, it stops before it changes anything:

What it finds	Why it stops
An existing WSL distribution	Someone set that up deliberately. The appliance overwrites nothing.
Docker already present — including installed and stopped	Docker Desktop is the most likely find on a company machine. It brings its own WSL distributions and its own network configuration; someone starting it months later collides with the appliance, and nobody will see the connection.
An existing `.wslconfig`	Same rule — the file holds someone’s settings.
Hardware virtualization disabled	No WSL2 at all.
Ports 80, 443 or 5100 in use	The proxy and the gateway need them.

There is no switch to skip this check. The appliance requires a dedicated device; a partially migrated installation is not supported.

A preflight run lists every finding at once and changes nothing, so you can check a candidate machine before you schedule the work.

The host address must be static

The container network configuration and the firewall rule each store the host address independently. An address change takes the appliance down. Nothing automatically detects and repairs the mismatch.

The installer therefore refuses a DHCP-assigned address. Give the machine a static address, or pass a documented DHCP reservation as an explicit argument with the reference to your IT ticket.

What you need before you start

Windows

Windows 11 22H2 or newer (build 22621+), 64-bit
Hardware virtualization enabled in BIOS/UEFI
A machine with no WSL distribution, no Docker and no .wslconfig
A static IPv4 address, or a documented DHCP reservation
Ports 80, 443 and 5100 free
Administrator rights, and a reboot slot — enabling the Windows features requires one
Network access during installation: the WSL distribution, the Docker Engine and CONNECT are downloaded

Linux

64-bit Linux with root access
Docker Engine 24 or newer with Compose v2
At least 20 GB free disk space
openssl and a correct system clock
A static address, ports 80 and 443 free

In both cases

A built HMI release, as an archive, to seed the appliance with. Without it the stack starts and says so clearly, but / has nothing to serve. Importing a release keeps the previous one in place, so a rollback is a symlink switch.

Trusting the appliance — the root CA

The appliance serves HTTPS. By default it uses its own internal certificate authority, because there is no public DNS name and no internet, so a public certificate is not available.

When you open the HMI from another device, plain HTTP is an insecure context. The viewer then loses encrypted persistence and the password gate, the CAD and GLB cache digest, copy buttons and VR/AR. localhost counts as a secure origin, so a single-seat PC works over HTTP. A panel PC or tablet in the plant network does not.

Three things to plan for per device:

Windows takes about two minutes and is scriptable by group policy.
Firefox keeps its own certificate store and does not use the Windows one.
iPadOS needs a second step after the profile is installed: Settings › General › About › Certificate Trust Settings. This is the single most common support case.

If your site has its own PKI, use it. Configure the appliance with a certificate from your authority. The devices already trust it, so they need no certificate setup.

Access protection: one authenticated origin, no roles

Authentication happens at the reverse proxy, in front of everything. Every route is covered: the HMI, the dashboard, the repository, the history, the gateway, and the WebSocket upgrade. Without credentials you get 401 everywhere, and nothing reaches the services behind the proxy.

There are two accounts. One is for people. Its password is printed exactly once, at the end of installation, and is stored nowhere. The other is a machine account used by the health check and test scripts.

The origin credentials are never passed through to CONNECT. The proxy strips the authorization header and injects the gateway’s API key behind it, so the browser never sees the key.

Two more points about login:

There is no login rate limiting. Basic authentication does not slow down guessing. The appliance sits in the plant network behind the firewall rule that restricts the gateway port — that is the whole of the protection against a determined attempt from inside the network.
Failed logins are indistinguishable. A wrong password and an unknown user produce the same response, byte for byte, and the response names none of the services behind the proxy.

Kiosk: what the panel shows when it is switched on

An appliance is usually a panel next to a machine, with no keyboard, browser controls or person to operate it. It boots directly into one document, without offering a document choice or allowing navigation away from it.

Two settings carry that:

Setting	What it does
Start document	The document the appliance’s own project manifest declares. That is the document the panel comes up with.
Mode lock	Locks the deployment to one workspace, typically the machine-information view. The workspace selector disappears; deep links that would switch workspace are ignored.

The start document comes from the project’s manifest, not a global setting. The appliance serves exactly one project, which names its own entry point. If the project has a single document and the deployment is mode-locked, the project list is also hidden.

Removing the mode lock is how a box is unlocked for commissioning. The full range of ways to open a document, deep links included, applies again from that point.

When a kiosk boot lands on nothing

A blank unattended panel gives no indication of the fault. If a kiosk cannot resolve a document at startup, it reports the reason on screen instead of opening something else:

What went wrong	What it means
No manifest	The address the panel was pointed at served no `project.json` — typically a 404, a 500, or a file that could not be parsed
No documents	The manifest was read, but it lists no documents
No start document	The manifest lists documents but names none of them as the one to start with
Start document missing	The named start document is not among the documents the manifest lists

All four are configuration faults in the delivered project, and all four are fixed on the project rather than on the appliance.

There is no backup and no restore

This is the largest open gap, and the reason the appliance is not released.

The appliance keeps its state in three volumes: the project repository and long-term archive, the signal history, and the certificate authority. The product has no backup or restore function for these volumes. Uninstalling leaves them in place, so reinstalling preserves their contents. If the volumes are lost, the product cannot recover them.

Until a backup path exists, treat the machine as disposable and take a snapshot at the virtualization layer before anything risky. Whatever you do, the volume that holds the certificate authority belongs in your own backup regime.