Skip to content

Docker Usage

Multi-platform images (amd64, arm64, s390x, ppc64le) are published on Docker Hub for every release.

docker pull pambrose/prometheus-proxy:4.6.0
docker pull pambrose/prometheus-agent:4.6.0

Basic Usage

In a container, localhost is the container itself, so these put the proxy and the agent on a network they share, and the agent reaches the proxy by its container name, given in PROXY_HOSTNAME. In a real deployment the agent runs on another host, inside the firewall, with PROXY_HOSTNAME set to the proxy's address and no shared network.

Proxy

# Create a network for the proxy and agent containers:
docker network create prometheus-proxy-net

# Start a proxy container on it, with its metrics enabled:
docker run --rm --name prometheus-proxy --network prometheus-proxy-net \
  -p 8080:8080 -p 50051:50051 \
  --env METRICS_ENABLED=true \
  pambrose/prometheus-proxy:4.6.0

Agent with Remote Config

Run the agent in another terminal. Its config, simple.conf, serves the proxy's and the agent's own metrics through the proxy, and fetches the proxy's from the PROXY_HOSTNAME host, which is why the proxy needs METRICS_ENABLED:

# Start an agent with a remote config, connecting to the proxy by its container name:
docker run --rm --network prometheus-proxy-net \
  --env PROXY_HOSTNAME=prometheus-proxy \
  --env AGENT_CONFIG='https://raw.githubusercontent.com/pambrose/prometheus-proxy/master/examples/simple.conf' \
  pambrose/prometheus-agent:4.6.0

# Scrape the proxy's and the agent's own metrics through the proxy:
curl http://localhost:8080/proxy_metrics
curl http://localhost:8080/agent_metrics

Running in the Background

The examples above run in the foreground: the container stays attached to your terminal and logs there until you stop it with Ctrl+C, and --rm then removes it. To keep a container running in the background, start it with --detach and give it a --name to manage it by. --restart unless-stopped also starts it again if it exits or Docker restarts, until you stop it. Docker doesn't allow --rm with --restart, so leave --rm out:

# Run the proxy in the background:
docker run --detach --name prometheus-proxy --restart unless-stopped \
  -p 8080:8080 -p 50051:50051 \
  pambrose/prometheus-proxy:4.6.0

# Run an agent in the background with a local config file:
docker run --detach --name prometheus-agent --restart unless-stopped \
  --mount type=bind,source="$(pwd)"/agent.conf,target=/app/agent.conf \
  --env AGENT_CONFIG=agent.conf \
  --env PROXY_HOSTNAME=proxy-host.example.com \
  pambrose/prometheus-agent:4.6.0

Manage a background container by its name:

docker ps --filter name=prometheus-          # check that they are running
docker logs --follow prometheus-proxy        # follow a container's log
docker restart prometheus-agent              # restart it, e.g. to pick up an edited agent.conf
docker stop prometheus-agent                 # stop it; it stays stopped when Docker restarts
docker rm prometheus-agent                   # remove the stopped container

To move a container to a new release, stop and remove it, then run it again with the new version's tag.

Production Setup

These run in the background under a restart policy, as described in Running in the Background.

Proxy with Admin and Metrics

# Production proxy with admin and metrics enabled, in the background:
docker run --detach --name prometheus-proxy \
  -p 8080:8080 \
  -p 50051:50051 \
  -p 8082:8082 \
  -p 8092:8092 \
  --env ADMIN_ENABLED=true \
  --env METRICS_ENABLED=true \
  --restart unless-stopped \
  pambrose/prometheus-proxy:4.6.0

Agent with Local Config File

# Agent with a local config file (bind mount), in the background:
docker run --detach --name prometheus-agent \
  -p 8083:8083 \
  -p 8093:8093 \
  --mount type=bind,source="$(pwd)"/prom-agent.conf,target=/app/prom-agent.conf \
  --env AGENT_CONFIG=prom-agent.conf \
  --env PROXY_HOSTNAME=proxy-host.example.com \
  --restart unless-stopped \
  pambrose/prometheus-agent:4.6.0

Container WORKDIR and user

The WORKDIR of both proxy and agent images is /app. Use /app as the base directory in --mount target paths.

Both images run as a non-root user with UID and GID 1001, given by number, so a mounted config or certificate must be readable by that user. In Kubernetes, runAsNonRoot can check the user without a runAsUser.

Docker Compose

services:
  proxy:
    image: pambrose/prometheus-proxy:4.6.0
    ports:
      - "8080:8080"    # HTTP scrape port
      - "50051:50051"  # gRPC agent port
      - "8082:8082"    # Metrics port
      - "8092:8092"    # Admin port
    environment:
      - ADMIN_ENABLED=true
      - METRICS_ENABLED=true
      - SD_ENABLED=true
      - SD_TARGET_PREFIX=proxy:8080
    restart: unless-stopped

  agent:
    image: pambrose/prometheus-agent:4.6.0
    ports:
      - "8083:8083"    # Metrics port
      - "8093:8093"    # Admin port
    environment:
      - PROXY_HOSTNAME=proxy
      - ADMIN_ENABLED=true
      - METRICS_ENABLED=true
      - AGENT_CONFIG=agent.conf
    volumes:
      - ./agent.conf:/app/agent.conf:ro
    depends_on:
      - proxy
    restart: unless-stopped

For a stack you can start as-is, etc/compose/proxy.yml runs a proxy, an agent, and a Prometheus server that scrapes the proxy's and agent's own metrics through the proxy. From a checkout of the repository:

docker compose -f etc/compose/proxy.yml up

Prometheus is then at http://localhost:9090, with both targets up on its Targets page.

That runs the stack in the foreground until Ctrl+C. To run it in the background instead, add --detach; each service's restart: unless-stopped starts it again if it exits or Docker restarts:

docker compose -f etc/compose/proxy.yml up --detach
docker compose -f etc/compose/proxy.yml logs --follow   # follow the stack's logs
docker compose -f etc/compose/proxy.yml down            # stop and remove the stack

TLS with Docker

Mount your certificate files into the container:

# Proxy with TLS (no mutual auth):
docker run --rm \
  -p 8080:8080 \
  -p 50440:50440 \
  -p 8082:8082 \
  -p 8092:8092 \
  --mount type=bind,source="$(pwd)"/certs,target=/app/certs \
  --mount type=bind,source="$(pwd)"/tls.conf,target=/app/tls.conf \
  --env PROXY_CONFIG=tls.conf \
  --env ADMIN_ENABLED=true \
  --env METRICS_ENABLED=true \
  pambrose/prometheus-proxy:4.6.0

# Agent with TLS (no mutual auth):
docker run --rm \
  -p 8083:8083 \
  -p 8093:8093 \
  --mount type=bind,source="$(pwd)"/certs,target=/app/certs \
  --mount type=bind,source="$(pwd)"/tls.conf,target=/app/tls.conf \
  --env AGENT_CONFIG=tls.conf \
  --env PROXY_HOSTNAME=proxy-host:50440 \
  pambrose/prometheus-agent:4.6.0

Or, on a platform that passes secrets as environment variables, give them as PEM, with no file mounted:

# Proxy with TLS, its certificate and key given as environment variables, no file mounted:
docker run --rm \
  -p 8080:8080 \
  -p 50051:50051 \
  --env CERT_CHAIN_PEM="$(base64 < server.crt | tr -d '\n')" \
  --env PRIVATE_KEY_PEM="$(base64 < server.key | tr -d '\n')" \
  pambrose/prometheus-proxy:4.6.0

# Agent trusting the CA that signed the proxy's certificate, given as an environment variable:
docker run --rm \
  --mount type=bind,source="$(pwd)"/agent.conf,target=/app/agent.conf \
  --env AGENT_CONFIG=agent.conf \
  --env PROXY_HOSTNAME=proxy-host:50051 \
  --env TRUST_CERT_COLLECTION_PEM="$(cat ca.crt)" \
  pambrose/prometheus-agent:4.6.0

See TLS Setup for complete TLS configuration details.

Environment Variables

Common environment variables for Docker:

Proxy:
  PROXY_CONFIG            - Config file path or URL
  PROXY_PORT              - HTTP listen port (default: 8080)
  AGENT_PORT              - gRPC listen port (default: 50051)
  ADMIN_ENABLED           - Enable admin endpoints (default: false)
  ADMIN_PORT              - Admin port (default: 8092)
  METRICS_ENABLED         - Enable metrics (default: false)
  METRICS_PORT            - Metrics port (default: 8082)
  SD_ENABLED              - Enable service discovery (default: false)
  SD_PATH                 - SD endpoint path (default: "discovery")
  SD_TARGET_PREFIX        - SD target prefix

Agent:
  AGENT_CONFIG            - Config file path or URL (required)
  PROXY_HOSTNAME          - Proxy hostname (can include :port)
  AGENT_NAME              - Agent name
  ADMIN_ENABLED           - Enable admin endpoints (default: false)
  ADMIN_PORT              - Admin port (default: 8093)
  METRICS_ENABLED         - Enable metrics (default: false)
  METRICS_PORT            - Metrics port (default: 8083)
  MAX_CONCURRENT_CLIENTS  - Parallel scrape limit (default: 1)

Using the latest Tag

The latest tag always points to the most recent release:

docker pull pambrose/prometheus-proxy:latest
docker pull pambrose/prometheus-agent:latest

Pin versions in production

Use explicit version tags (e.g., 4.6.0) in production to avoid unexpected upgrades.