48 lines
4.4 KiB
Markdown
48 lines
4.4 KiB
Markdown
# 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](VHOSTS.md) and [Cache](CACHE.md).
|