docs(docker): warn bridge-mode users about FTP passive port × docker-proxy RAM footprint (#1646)

Reporter @TheFou (on Docker bridge mode with the default userland-proxy:
  true) saw ~2000 docker-proxy host processes spawn from the commented
  "50000-51000:50000-51000" line, pinning ~3.5 GB of host RAM before they
  had even logged in for the first time. The processes are host-level so
  they don't appear in `docker stats`, which makes the leak invisible.

  Linux's host-mode default in the same compose file sidesteps this
  entirely (zero docker-proxy cost) - the issue only fires when a user
  forces bridge mode (typically Docker Desktop on macOS / Windows).

  The 1001-port FTP passive range is load-bearing on the VP server side
  (virtual_printer/ftp_server.py:567-574 documents the widening from 100
  ports as multi-VP collision-avoidance headroom against birthday-style
  collisions when bind_ip=0.0.0.0). Reverting it would regress multi-VP
  installs to solve a problem that only exists for bridge-mode users.

  Fix is documentation, not code. Added a warning block above the
  commented FTP-passive line pointing bridge-mode users at
  { "userland-proxy": false } in /etc/docker/daemon.json. Reporter
  confirmed this clears the issue on their setup - the kernel does NAT
  directly via iptables/nftables in that mode, no per-port host process
  needed. Only side-effect is that connections originating from
  127.0.0.1 on the host itself can't reach the container, which doesn't
  matter for nearly every Bambuddy install.
This commit is contained in:
maziggy
2026-06-05 09:36:30 +02:00
parent 54389a54aa
commit ccdbdabdb7
2 changed files with 18 additions and 0 deletions
+15
View File
@@ -35,6 +35,21 @@ services:
# - "322:322" # Virtual printer RTSP camera (X1/H2/P2; proxy mode + non-proxy modes with a target printer)
# - "2024-2026:2024-2026" # Virtual printer proprietary ports (A1/P1S)
# - "50000-51000:50000-51000" # Virtual printer FTP passive data (widened from 50000-50100 for multi-VP headroom)
#
# ⚠️ Bridge-mode + Docker's default userland proxy: the 1001-port FTP
# passive range spawns ~2000 docker-proxy host processes (IPv4+IPv6
# × 1001 ports), each pinning ~3.5 MB of host RAM, for a ~3.5 GB
# footprint that doesn't show up in `docker stats` because it's
# host-level, not container-level (#1646). Linux's host-mode default
# above sidesteps this entirely. If you genuinely need bridge mode
# (e.g. Docker Desktop on macOS/Windows), set
# { "userland-proxy": false }
# in /etc/docker/daemon.json and restart Docker. Confirmed to clear
# the issue by the reporter; the kernel does NAT directly via
# iptables/nftables, no per-port host process needed. Only side-
# effect is that connections originating from 127.0.0.1 on the host
# itself can't reach the container — fine for nearly every
# Bambuddy install.
volumes:
- bambuddy_data:/app/data
- bambuddy_logs:/app/logs