Installation & Deployment

These must be running and reachable before the containers start. None of them are deployed by this guide.

Network access to the hub.friendly-tech.com Docker registry, which publishes all four images:

Access to the deployment files as well: the compose file for your topology, and the environment values described in Environment Configuration.

Both topologies put the containers on a bridge network the services address by container name: a worker reaches its sidecar at http://mcp-tr-emul:8082, the gateway reaches a worker at http://test-runner-<name>:8083. That traffic never leaves the host and needs no firewall rule.

In the worker-pool topology the network is test-runner-net and it is external — shared by the gateway stack and every worker stack, so it has to exist before any of them start:

Peers outside Docker on the same host are reached through host.docker.internal, which the single-stack compose file maps explicitly:

When the host cannot reach hub.friendly-tech.com, pull on a connected machine, export, transfer, and load. Note that the runner image bundles Chromium and the Claude CLI, so it is large — budget accordingly.

An explicit --platform matching the offline host’s architecture is required; without it docker pull picks the connected machine’s architecture.

On the offline host:

The runner still needs outbound HTTPS to the Anthropic API at run time — the image being local does not make the agent offline-capable.

Create the shared bind mount the MCP services exchange generated tree files through, and — for the worker pool — the external network and volumes:

The runner’s own state lives in named volumes, not on the host:

The environment templates live in this repository, so a change to a service and a change to its configuration can travel in the same commit:

They are templates: placeholders only, no host values, and no filled-in copy belongs in git.

Three layers decide what a runner actually uses, in increasing precedence:

So a value edited in the UI outranks the one set at deploy time and survives a redeploy. In the worker pool a fourth step sits on top: the gateway PUTs the chosen environment profile onto the worker immediately before a run, which replaces the target URLs and credentials for that run. Values in the compose file are therefore startup fallbacks, not the source of truth — see Environment Profiles.

One runner with its two sidecars, published on the host. test_runner/docker-compose.yml in this repository is that stack; deploy it with Compose or paste it into Portainer → Stacks → Add Stack.

Set the values from docker/.env.example in the .env next to the compose file, or in the stack’s Env array. At minimum: TR069_ACS_URL, TR069_EMULATOR_URL, FT_PORTAL_*, and — if TestRail is used — TESTRAIL_EMAIL / TESTRAIL_API_KEY. IOT_EMULATOR_URL is optional — it only seeds the mcp-iot-emul sidecar’s startup default, since every call carries the active profile’s iot_emulator_url instead.

Deploy in this order; each step assumes the previous one succeeded.

With Portainer credentials configured, Add Worker provisions the worker stack for you (saving an environment profile provisions nothing: the sidecars are bundled). Provisioning is best-effort and inert when those credentials are unset — see Portainer Auto-Provisioning.

Inside a stack, depends_on orders the runner after mcp-tr-emul and mcp-iot-emul. Nothing gates on the environment under test: the emulator, ACS and portals live outside these stacks, so Compose cannot wait for them. They only need to be up when a run starts, not when the container does — a runner with an unreachable environment starts fine and fails at the first preflight.

The one dependency that must exist before start is the logged-in Claude CLI directory being bind-mounted (Required External Dependencies).

start.sh brings the container up in a fixed order, and each step announces itself. Expect, in this order: Xvfb on display :99, x11vnc on 5900, the noVNC proxy on 6080, the test-case sync from image to volume, the Playwright browser checks, Starting Playwright MCP server on port 3100, and finally Starting Test Runner API on port 8083. A container that never reaches the last line is stuck in one of the browser installs, not in the API.

Both the runner and the gateway serve /health, which is also what their container healthchecks call:

Then open the UI:

In a worker-pool deployment that URL is the gateway, so it asks you to log in first — see Accounts & Roles.

The deployment is only proven once a case actually executes:

A run that fails at the first preflight points at the environment (emulator, ACS, portal), not at the deployment.

Reachable on the Docker network or inside the container only.

Run reports are not in the container log — they live on the run-reports volume and are served by the UI.

Restarting a worker mid-run loses that run: the Chromium and its Playwright session live in the container. Drain the worker first (disable it in the Workers tab) when the restart can wait.

The named volumes survive — imported cases, reports, notes and settings.json are kept. New cases bundled in a newer image are copied into the test-cases volume on start without overwriting existing files, so a locally edited case is never clobbered by an upgrade.

Upgrade the gateway and the workers together: they share GATEWAY_SECRET and the forwarded-identity contract.

If the log stops before Starting Test Runner API on port 8083, the container is still in start.sh — usually a Playwright browser install without network access to the browser CDN.

Symptom: the UI loads, runs start, but the Live Browser view shows nothing.

Fix:

Symptom: runs fail unpredictably, often on pages with heavy tables.

Cause: shared memory. Chromium needs far more than Docker’s default 64 MB /dev/shm.

Fix: confirm shm_size: '2gb' on the runner service and recreate the container.

Symptom: the gateway authenticates you, but every action against a worker bounces back to the login screen.

Cause: GATEWAY_SECRET differs between the gateway and that worker, so the worker rejects the forwarded identity.

Fix:

They must match exactly. Watch for a doubled $ that was meant as a literal (Secrets).

Cause: the profile’s emulator and portal URLs point at different stands, so parameters are applied on one environment while the test verifies another.

Fix: check the environment profile in Environments: emulator_url, acs_url, iot_emulator_url and ft_portal_url must all belong to the same stand.

Cause: TESTRAIL_API_KEY / TESTRAIL_EMAIL are unset. They deliberately have no fallback in the compose files (Secrets).

Fix: set them in the Env array or .env and recreate the container, or enter them in the Settings tab, which persists them on the run-reports volume.

Cause: the mounted Claude CLI config has no valid session.

Fix: log in with the CLI on the host, in the directory CLAUDE_CONFIG_DIR points at, and confirm the mount:

Stop the process holding the port, or change the published port in the compose ports: mapping.

Collect before contacting Friendly Tech support: