catbee/jaeger-auth repository overview

⁠Jaeger with Basic Authentication

A Jaeger 2.20.0 Docker image with a Caddy reverse proxy providing Basic Authentication for the Jaeger UI.

⁠Features

• Jaeger 2.20.0
• Caddy 2.10 Alpine
• Basic Authentication for the Jaeger UI
• Password hash generated at container startup
• Custom unauthorized (401) error page
• OTLP gRPC receiver
• OTLP HTTP receiver
• Jaeger UI exposed through an authenticated reverse proxy
• Graceful shutdown of Jaeger and Caddy
• Lightweight Alpine-based runtime image

⁠Architecture

The image runs two processes:

                    ┌──────────────────────┐
                    │      Caddy :16686    │
                    │   Basic Auth / UI    │
                    └──────────┬───────────┘
                               │
                               │ reverse proxy
                               ▼
                    ┌──────────────────────┐
                    │     Jaeger :16687    │
                    │      Query/UI        │
                    └──────────────────────┘

OpenTelemetry applications
          │
          ├──────── OTLP gRPC ────────► :4317
          │
          └──────── OTLP HTTP ────────► :4318

The Jaeger UI is not exposed directly. Requests to port 16686 are handled by Caddy, which requires HTTP Basic Authentication before proxying requests to Jaeger's query service.

⁠Quick Start

Run the container with a username and password:

docker run -d \
  --name jaeger-auth \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -e JAEGER_AUTH_USER=admin \
  -e JAEGER_AUTH_PASSWORD=change-me \
  catbee/jaeger-auth:2.20.0

Open the Jaeger UI:

http://localhost:16686

The UI requires the configured username and password.

⁠Configuration

⁠Required Environment Variables

Both variables are required. The container exits if either variable is missing.

⁠Ports

⁠OpenTelemetry

The image configures Jaeger to receive OpenTelemetry traces through both supported OTLP protocols.

⁠OTLP gRPC

localhost:4317

Example OpenTelemetry endpoint:

http://localhost:4317

⁠OTLP HTTP

localhost:4318

Example OpenTelemetry endpoint:

http://localhost:4318

Configure your OpenTelemetry application to export traces to the appropriate endpoint.

⁠Jaeger UI Authentication

The Jaeger UI is protected by Caddy using HTTP Basic Authentication.

At startup, the container:

1. Validates JAEGER_AUTH_USER.
2. Validates JAEGER_AUTH_PASSWORD.
3. Generates a password hash using Caddy.
4. Starts Jaeger.
5. Starts Caddy.
6. Caddy uses the generated credentials to protect the UI.

The password itself is not written into the Caddy configuration.

⁠Unauthorized Requests

Unauthorized requests receive an HTTP 401 response.

The image includes a custom 401.html page that is returned for unauthorized UI requests.

The response also includes:

WWW-Authenticate: Basic

which causes compatible clients and browsers to request Basic Authentication credentials.

⁠Image Details

⁠Docker Compose

Example docker-compose.yml:

services:
  jaeger:
    image: catbee/jaeger-auth:2.20.0
    container_name: jaeger-auth
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    environment:
      JAEGER_AUTH_USER: admin
      JAEGER_AUTH_PASSWORD: change-me

Start the service:

docker compose up -d

View logs:

docker compose logs -f jaeger

⁠Using OpenTelemetry

Configure your application to export traces to the Jaeger container using OTLP.

For Docker Compose, other services can use:

jaeger:4317

for OTLP gRPC or:

jaeger:4318

for OTLP HTTP.

For applications running on the host:

localhost:4317

or:

localhost:4318

⁠Security

The Jaeger UI is protected with HTTP Basic Authentication.

However, JAEGER_AUTH_PASSWORD is supplied as an environment variable and is used to generate the password hash when the container starts.

For production deployments:

• Use a strong password.
• Avoid exposing Jaeger directly to the public internet.
• Prefer a secure network or reverse proxy.
• Use HTTPS when authentication credentials are transmitted over an untrusted network.
• Store credentials using your platform's secret-management mechanism where available.

⁠Pull the Image

docker pull catbee/jaeger-auth:2.20.0

⁠Run the Image

docker run -d \
  --name jaeger-auth \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -e JAEGER_AUTH_USER=admin \
  -e JAEGER_AUTH_PASSWORD=change-me \
  catbee/jaeger-auth:2.20.0

Then open:

http://localhost:16686

⁠Graceful Shutdown

The container manages both Jaeger and Caddy processes.

When the container receives SIGTERM or SIGINT, the startup script stops both services and waits for them to exit cleanly.

⁠Image

catbee/jaeger-auth:2.20.0

⁠License

Jaeger and Caddy are distributed under their respective open-source licenses.

Refer to the upstream Jaeger and Caddy projects for complete licensing information.