Docker Usage
Multi-platform images (amd64, arm64, s390x, ppc64le) are published on Docker Hub for every release.
Basic Usage
Proxy
# Start a proxy container:
docker run --rm -p 8080:8080 -p 50051:50051 \
pambrose/prometheus-proxy:4.4.0
Agent with Remote Config
# Start an agent with a remote config:
docker run --rm \
--env AGENT_CONFIG='https://raw.githubusercontent.com/pambrose/prometheus-proxy/master/examples/simple.conf' \
pambrose/prometheus-agent:4.4.0
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.4.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.4.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.4.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 \
--restart unless-stopped \
pambrose/prometheus-agent:4.4.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.4.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.4.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:
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.4.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.4.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:
Pin versions in production
Use explicit version tags (e.g., 4.4.0) in production to avoid unexpected upgrades.