RustProxy/docs/DOCKER_DISCOVERY.md

Docker discovery and generated Vhosts

RustProxy discovers published Docker services through a separate read-only Docker agent on each Docker host. The RustProxy core does not need Docker-socket access. The agent observes Docker containers; RustProxy turns enabled assignments into dynamic, ordinary HTTP Vhosts.

Set up a Docker host

1. On the Docker host, review docker-agent/README.md, docker-agent/docker-agent.env.example and docker-agent/install.sh.
2. Build/install the Go agent with cd docker-agent && sudo ./install.sh; the installer runs tests, installs the service, initializes a Bearer token and an HTTPS certificate, and prints the SHA-256 certificate fingerprint.
3. Restrict the agent port (default shown in the example environment: 9876) to the RustProxy host/network. Access to the Docker socket is privileged, even though the agent's HTTP API is read-only.
4. In Settings → Docker agents, create an agent with an endpoint such as https://10.10.0.21:9876, its token and printed fingerprint, base domain, selected listener IDs and optional certificate/ACL/default backend IP.
5. Use Docker vhosts → Refresh agents and check that the agent observation is successful before publishing any service.

The agent normally presents its own persistent self-signed certificate; pin the exact fingerprint in RustProxy. When using a CA-issued agent certificate, normal TLS CA/hostname verification can be used instead. Plain HTTP exposes the bearer token and should be avoided.

What discovery reports

• Running containers with Docker-published, non-loopback TCP ports; it does not turn an internal-only container port into a directly reachable service.
• Usable Docker-host interface/IP addresses and each published host binding, allowing an explicit backend address selection when the host has multiple networks.
• Current service status, container metadata and optional aliases. The agent does not install applications, change Docker network rules or deploy TLS on their behalf.

Agent inventory polling is separate from the panel's live status refresh. A new agent may initially show WAITING until the first poll, not a failure. Refresh agents requests an immediate agent update. Actual failures report a reason; a temporary agent outage can preserve the last successful inventory while a successful missing-service observation can lead to a generated route returning 503 until the service returns.

Publish a discovered application

In Docker vhosts, select the service and set:

Option	Guidance
Hostname / aliases	A short name expands under the agent base domain; a full FQDN stays as entered. Configure public DNS separately.
Backend IP/port	Pick a detected, reachable Docker-host address or the configured automatic option. Docker host/firewall binding must permit RustProxy to connect.
HTTP / HTTPS upstream	Match the container's actual service protocol; review origin TLS verification and Host behavior.
Frontend listeners / certificate	Selected through the agent defaults and RustProxy configuration; ensure certificate covers the generated name.
Force HTTPS / WebSockets	Enable only when needed and when the right frontend listeners exist.
Cache / compression / transforms	Optional; obey the global limits and privacy policy of the application.
Health / ACL / timeouts	Set checks and protections appropriate for the application, not just the Docker host.

Use Publish and test the resulting hostname. Edits to an already published service use its own Apply changes action; unpublishing does not stop its Docker container. Hidden rows in the page are only a browser view preference, not a security policy.

Troubleshooting

• WAITING: first poll not yet observed; refresh and inspect the agent endpoint.
• Agent error: verify firewall, TLS fingerprint/CA, bearer token, service state, advertised host and TCP route.
• 503 generated Vhost: verify running container, published TCP port, selected IP/bind address, backend protocol and health check.
• Wrong application hostname: check base-domain expansion, aliases, DNS and conflicting ordinary Vhosts.
• Docker service not listed: agent reports only eligible running containers with published non-loopback TCP bindings.

For agent operations and its security model see docker-agent/README.md. For normal routing, health and cache controls see Vhosts and Cache.