v0.34.0_fina;

docs/CONTAINER.md

@@ -1,44 +1,38 @@
-# Container / OCI deployment
+# Docker / OCI deployment
 
-RustProxy ships a baseline multi-stage `Dockerfile`. It compiles the locked Rust
-release and runs it as the unprivileged `rustproxy` user (UID 10001). The core image does
-not mount the Docker socket. Docker discovery uses the separate `docker-agent/` process on
-each Docker host, so the proxy container never needs Docker-socket access. See
-[Docker discovery](DOCKER_DISCOVERY.md).
+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 locally with a normal OCI builder:
-
-```bash
-docker build -t rustproxy:0.29.1 .
-```
-
-Persist `/var/lib/rustproxy`; it contains the SQLite database, certificates and the
-optional cold-cache tier. The default container proxy listener is `0.0.0.0:8080`.
-Administration remains `127.0.0.1:9090` inside the container and is intentionally
-not remotely reachable by merely publishing port 9090.
+## Build and start
+
+Run from the repository root:
 
 ```bash
+docker build -t rustproxy:0.34.0 .
 docker volume create rustproxy-data
-docker run --rm -d --name rustproxy \
+docker run -d --name rustproxy \
   -p 8080:8080 \
   -v rustproxy-data:/var/lib/rustproxy \
-  rustproxy:0.29.1
+  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:
+
+```bash
 docker exec rustproxy rust-proxy admin setup-token
 ```
 
-To expose administration, first enable administration HTTPS in the persisted
-RustProxy configuration and choose a certificate, then bind the administration
-listener to a non-loopback address. Publish the admin port only after HTTPS is
-active. Plain remote HTTP keeps the legacy explicit risk gate.
+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.
 
-The runtime image includes Python, venv/pip, OpenSSL and distribution Certbot packages
-for Cloudflare, OVH and RFC2136 fallback. RustProxy prefers its own pinned Certbot
-environment under `/var/lib/rustproxy/acme-python`; because `/var/lib/rustproxy` is the
-persisted volume, that environment survives container replacement. If pip setup is not
-possible, the image can fall back to the distribution Certbot binaries already in `PATH`.
+## Persistent data and ports
 
-For access-log files, prefer a writable path under `/var/lib/rustproxy` or mount a
-separate writable log volume. The built-in JSON file sink is disabled by default.
-Low ports such as 80/443 require an explicit container capability or host port
-mapping; the image itself does not run as root.
+- 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](DOCKER_DISCOVERY.md).
+
+## 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.