Skip to content

docs: add proxy troubleshooting section to Docker deployment page #45

@brandonrc

Description

@brandonrc

Context

Issue #395 on the backend repo reported persistent 503 health check failures for all internal services (meilisearch, trivy, openscap, dependency-track). Root cause was corporate proxy settings (HTTP_PROXY/HTTPS_PROXY) leaking into containers and routing internal traffic through the proxy.

This is a common scenario in enterprise and government environments. The Docker deployment page at docs/deployment/docker.mdx has an existing troubleshooting section but doesn't cover proxy-related issues.

What to add

Add a troubleshooting entry to the Docker deployment guide covering:

  1. Symptom: All services show as unhealthy (503 Service Unavailable) in the dashboard and backend logs, even though individual containers are running and healthy
  2. Cause: Host-level HTTP_PROXY/HTTPS_PROXY vars propagated into the backend container, causing internal health checks to route through the proxy
  3. Diagnosis: How to identify this (look for external IPs in tcpdump on the compose bridge, check env | grep -i proxy inside the backend container)
  4. Fix: The compose files now set no_proxy for internal service names (PR fix: add no_proxy to backend for container-to-container traffic artifact-keeper#413). For users on older versions, manually add service hostnames to NO_PROXY
  5. Prevention: Note about .env proxy configuration and the .env.example documentation

Could also be worth adding a general "Corporate Proxy" section since Dependency-Track has its own proxy settings (ALPINE_HTTP_PROXY_*) and users behind proxies will need to configure both.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationv1.2.0Targeted for v1.2.0 release

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status

    Todo

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions