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.
31 lines
1.6 KiB
Markdown
31 lines
1.6 KiB
Markdown
# 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
|
|
1. Decide early whether to use host networking (`--network host`) or explicit port mapping with a known internal IP.
|
|
2. If using host network, bind the service to `0.0.0.0` on a fixed, documented port and point the reverse proxy to the host IP.
|
|
3. If using bridge mode, ensure the reverse proxy can reach the container by name or fixed IP.
|
|
4. Document the chosen network topology in the RUNBOOK.
|
|
5. 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.
|