94 lines
6.9 KiB
Markdown
94 lines
6.9 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
|
|
|
|
Install the **optional Docker agent on each Linux Docker host**, not on the RustProxy server. It is distributed as a separate `rustproxy-docker-agent` DEB/RPM package and is **not built as FreeBSD `pkg`**. Docker Engine, systemd and access to `/var/run/docker.sock` are required at runtime.
|
|
|
|
### Option A: prebuilt DEB/RPM (recommended)
|
|
|
|
After configuring the signed APT/DNF RustProxy repository (see [Installation](INSTALL.md)):
|
|
|
|
```bash
|
|
# Debian / Ubuntu
|
|
sudo apt update && sudo apt install rustproxy-docker-agent
|
|
|
|
# Or on RHEL / Rocky / Alma / Fedora
|
|
sudo dnf install rustproxy-docker-agent
|
|
```
|
|
|
|
For offline/local installation use `sudo apt install ./rustproxy-docker-agent_<version>-<release>_amd64.deb` or `sudo dnf install ./rustproxy-docker-agent-<version>-<release>.x86_64.rpm`. The post-install script generates a random token and self-signed TLS certificate on first install, creates a systemd service, and preserves credentials across upgrades. It does not print the token to unattended installation logs.
|
|
|
|
```bash
|
|
sudo rustproxy-docker-agent info # endpoint, TLS fingerprint, validity, token status
|
|
sudo rustproxy-docker-agent info --show-token # full secret token: run locally as root
|
|
sudo systemctl status rustproxy-docker-agent
|
|
```
|
|
|
|
### Option B: build and install manually (optional)
|
|
|
|
```bash
|
|
cd docker-agent
|
|
go test ./...
|
|
sudo ./install.sh
|
|
```
|
|
|
|
Go 1.22+ is required only for the manual build, not for a DEB/RPM installation. The manual installer uses the same Go CLI to create credentials and TLS identity and displays the token interactively. Detailed custom systemd setup and migration between manual/package-managed services are in [docker-agent/README.md](../docker-agent/README.md).
|
|
|
|
### Connect to RustProxy
|
|
|
|
1. Allow port `9876` **only from the RustProxy server** in the Docker-host firewall. The default example listens on `0.0.0.0:9876`.
|
|
2. In **Settings → Docker agents**, create an agent with an endpoint such as `https://10.10.0.21:9876`, its Bearer token and certificate SHA-256 fingerprint, base domain, selected listener IDs, and optional certificate/ACL/default backend IP.
|
|
3. Use **Docker vhosts → Refresh agents** and check that discovery succeeds before publishing.
|
|
|
|
The self-signed certificate is persistent. RustProxy pins its exact fingerprint; if replaced, update the pin. A trusted CA-issued certificate can use normal CA and hostname verification instead. Plain HTTP is available only by explicit opt-out and exposes the token in transit.
|
|
|
|
To inspect or rotate credentials after installation:
|
|
|
|
```bash
|
|
sudo rustproxy-docker-agent info --json
|
|
sudo rustproxy-docker-agent print-fingerprint
|
|
sudo rustproxy-docker-agent rotate-token
|
|
sudo systemctl restart rustproxy-docker-agent
|
|
sudo rustproxy-docker-agent show-token # secret: update it in RustProxy settings
|
|
```
|
|
|
|
A token change invalidates the previous token after service restart. The agent logs certificate details and **redacted** token status at startup. The Docker socket is root-equivalent access; isolate the service account and host even though the HTTP inventory endpoint is read-only.
|
|
|
|
## 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** | Select up to eight reusable ACL profiles per app or inherit the agent's defaults; optional inline ACL remains independently enforced. Explicit denies and country blocks beat merged allows. Test allowed and blocked clients. |
|
|
|
|
To deliberately assign a domain not covered by the agent's **named frontend certificate**, enable **Force certificate mismatch** in the per-service editor and confirm the risk. This records `allow_certificate_mismatch: true` on that publication only. Without consent, the server rejects the incompatible mapping. The client browser may still reject the TLS handshake; a matching SAN certificate is strongly preferred. The agent's own outbound TLS fingerprint validation is unaffected.
|
|
|
|
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).
|