RustProxy/docs/CONTAINER.md

Docker / OCI deployment

The included Dockerfile compiles RustProxy with a Rust 1.99 build image and runs it on Debian as an unprivileged rustproxy account (UID 10001). It includes Python, Certbot and DNS-plugin packages for certificate handling. The main container does not need the Docker socket.

Build and start

Run from the repository root:

docker build -t rustproxy:0.34.0 .
docker volume create rustproxy-data
docker run -d --name rustproxy \
  -p 8080:8080 \
  -v rustproxy-data:/var/lib/rustproxy \
  rustproxy:0.34.0

In the image, the default HTTP frontend binds 0.0.0.0:8080. The admin listener defaults to 127.0.0.1:9090 inside the container. Simply publishing container port 9090 does not make that loopback listener reachable from a remote host. Initialize the administrator from a local container shell:

docker exec rustproxy rust-proxy admin setup-token

Provide a secure, private path for first-time panel access. If remote administration is required, configure its own HTTPS mode, certificate and an intentional non-loopback listener before mapping the port publicly; restrict it with firewall policy. Never expose plain HTTP administration as a convenience.

Persistent data and ports

• Mount /var/lib/rustproxy persistently for SQLite, private keys, certificate profiles and optional COLD cache. Back it up securely and keep volume ownership correct.
• Map the chosen HTTP and HTTPS TCP ports. If enabling HTTP/3, publish the corresponding UDP port too, and allow it through the host firewall.
• If you need low-numbered container ports, use host-port forwarding or deliberate capability settings; the image runs without root privileges.
• Store file access logs under a writable location/volume if enabled. The built-in on-disk access-log sink is not necessarily on by default.
• Managed ACME material in the persisted volume survives container replacement. DNS credentials and external mounts must be protected and carried over separately.

For Docker-based application discovery, install the separate Docker agent on each target host and connect it over the supported restricted interface. See Docker discovery.

Upgrade and validate

Build a reviewed new image, preserve the volume, make an encrypted application backup and deploy with a maintenance window. Verify configuration compatibility, listener reachability, frontend certificates, backup/restore and live traffic. The supplied 0.34.0 source candidate is not itself a production-tested OCI image.