NODEDC_PLATFORM/services/dc-amd-connector/README.md

DC AMD Connector

DC AMD Connector runs on the adjacent AMD Windows machine. It is a restricted HTTP CONNECT proxy for the NODE.DC map path:

NAS DC AMD Proxy -> 172.22.0.183:8791 -> AMD VPN -> Cesium / Bing

It is not a general-purpose proxy:

• only authenticated CONNECT requests are accepted;
• only port 443 is accepted;
• only Cesium Ion and required Bing imagery hosts are accepted;
• ordinary HTTP proxy requests are rejected;
• the Ion bearer token stays inside the end-to-end TLS connection from NAS to Cesium and is not processed or logged by this connector.

The Windows host owns the VPN. The NAS uses only the stable LAN address in .env, never an OpenVPN adapter address or a changing public VPN exit IP.

First run on the AMD machine

1. Start Docker Desktop and wait for its engine to be running.

2. Open PowerShell as Administrator and run install.ps1 from this package folder. It verifies source checksums, copies the package to C:\\NODEDC\\dc-amd-connector, creates a local random access token without printing it, binds port 8791 only to 172.22.0.183, scopes Windows Firewall to NAS 172.22.0.222, constrains the container to one CPU, 256 MB, 64 processes and 4096 file descriptors, and starts the container. It also adds a launcher to the current user's Windows Startup folder. At the next user sign-in it uses the Docker Desktop CLI when available, otherwise its installed application; the unless-stopped restart policy then restores this container.

   powershell -NoProfile -ExecutionPolicy Bypass -File .\\install.ps1
   

3. Do not send the runtime secret in chat or put it into a source file. The next NAS patch will provision the same value in a root-owned secret file through an operator-only transfer.

Docker Desktop on the WSL 2 backend is a desktop application, not an unattended Windows boot daemon. Thus this recovery guarantee starts after the configured Windows user signs in. Before a sign-in, the map must use its offline/tile-cache path. No Windows route, VPN, DNS, proxy setting or other application's traffic is modified.

Operations and migration

Run these commands from an elevated PowerShell window:

cd C:\\NODEDC\\dc-amd-connector
docker compose ps
docker compose logs --tail 100
docker compose restart

docker compose down is an intentional stop and removes the container; restore it with docker compose up -d. The auto-start launcher is removed by uninstall.ps1.

To move to a different adjacent Windows host: install this same package there with its stable LAN address (-BindAddress) and verify its VPN tunnel first. It creates a fresh local access secret. Only then may the separate NAS pairing patch be changed to the new host; never run two active pairings against the same NAS endpoint.

Verification

The connector health check uses the local runtime secret inside the container. It is expected to become healthy without making any external request. The following local check proves a permitted TLS tunnel through the current AMD VPN without revealing the access token:

docker exec dc-amd-connector node -e "const fs=require('fs'),net=require('net');const t=fs.readFileSync('/run/dc-amd-secrets/connector-access','utf8').trim();const s=net.connect(8791,'127.0.0.1',()=>s.write('CONNECT api.cesium.com:443 HTTP/1.1\r\nHost: api.cesium.com:443\r\nProxy-Authorization: Bearer '+t+'\r\n\r\n'));s.once('data',d=>{const v=d.toString('ascii');console.log(v.split('\r\n')[0]);s.destroy();process.exit(v.startsWith('HTTP/1.1 200')?0:1)});s.on('error',e=>{console.error(e.message);process.exit(1)})"

Expected output is HTTP/1.1 200 Connection Established. If the AMD VPN is off, this test must fail; it must never silently move live Cesium traffic to the NAS.