JC Beasley
0bd719ab91
- Create patterns/ directory with README, manifest, and 10 initial patterns covering Ollama JSON fallback, API escaping, deprecation, PTY auth, queue-poll, LLM-as-parser, credential rotation, reverse proxy binding, human approval gates, and transient retry. - Wire pattern loading into architecture/pipeline.js based on task tags. - Update architecture/orchestrator.js to load patterns and surface them in the system prompt. - Update MEMORY.md, ARCHITECTURE.md, and CONTEXT.md to document the registry and record the decision.
1.6 KiB
1.6 KiB
Pattern: Reverse Proxy + Container Port Binding
Symptom
A self-hosted Docker service (Nextcloud AIO, ComfyUI, etc.) is deployed behind a reverse proxy such as Nginx Proxy Manager. The service is unreachable, returns 502/504, or binds to the wrong network/interface. Docker network complexity, port mappings, and internal DNS all become debugging obstacles.
Affected Projects
- Nextcloud AIO on
bve.beawit.net - Any future self-hosted service deployed behind Nginx Proxy Manager
Root Cause
Containerized services often bind to localhost or a Docker-internal IP by default. A reverse proxy running on the host or in another container cannot reach them without explicit port binding and network configuration. NAT, firewall, and Docker bridge behavior add confusion.
Standard Fix
- Decide early whether to use host networking (
--network host) or explicit port mapping with a known internal IP. - If using host network, bind the service to
0.0.0.0on a fixed, documented port and point the reverse proxy to the host IP. - If using bridge mode, ensure the reverse proxy can reach the container by name or fixed IP.
- Document the chosen network topology in the RUNBOOK.
- Verify reachability from the reverse proxy host before declaring the deployment done.
When to Apply
- Every new containerized service that will be exposed through a reverse proxy.
- Any existing service with intermittent 502/504 or binding issues.
Verification
- Reverse proxy can curl the backend service directly.
- External HTTPS access returns expected responses.
- Configuration survives container restart.
Related Patterns
- None yet.