traefik/whoami Docker Setup and Request Inspection

What traefik/whoami Tests in a Docker Network

traefik/whoami addresses a specific testing problem: showing which backend received a request and what that backend observed. Its root endpoint prints the container hostname, local IP addresses, `RemoteAddr`, HTTP method and path, and request headers. This can expose differences involving container names, proxy routing, loopback addresses, IPv4 or IPv6 resolution, and the client address visible inside the Docker network.

The project is primarily aimed at engineers testing reverse proxies, Docker networking, TLS, WebSockets, and health-check behavior. It is also useful when a request reaches some service but the next debugging question is which instance handled it. The repository contains an OpenAPI specification, a gRPC definition, generated gRPC files, and tests for response content. Those entries indicate a diagnostic service that covers several request and response patterns rather than a general web framework.

whoami does not present itself as a business application, persistence layer, or authentication service. Its value comes from returning controlled information about the process, its environment, and its network. That narrow purpose also creates a boundary. A successful route inspection does not establish that an application handles authorization, data validation, persistence, or transactions correctly.

Several paths serve distinct test jobs. `/api` returns diagnostic information as JSON, `/echo` accepts WebSocket traffic, `/data` produces a response of a requested size, and `/health` can return a status chosen through a previous `POST`. The repository also documents gRPC calls to `whoami.Whoami/Whoami` and `whoami.Whoami/Bench`. These capabilities make the server a compact fixture for checking whether several kinds of traffic reach a selected container.

HTTP, WebSocket, and gRPC Processing in whoami

The Go module is named `github.com/traefik/whoami` and declares Go `1.26.0`. Direct dependencies include `github.com/gorilla/websocket`, `google.golang.org/grpc`, and `google.golang.org/protobuf`. Based on those dependencies and the repository layout, WebSocket and gRPC are separate request paths alongside the documented HTTP routes. The main application assembly is in `app.go`, while `content.go` and `content_test.go` cover diagnostic content.

The root path renders request and network information as text. The JSON path `/api` returns whoami information and extra fields. Both documented paths support `env=true`, which adds environment variables to the response. This setting can help locate missing configuration, but it can also expose sensitive values. The README does not document variable filtering, redaction, access control, or a production warning for this option.

A `wait` parameter on the root route delays the response. Its value follows Go's `time.Duration` format, and the documented example uses `100ms`. A proxy test can therefore exercise a known short delay. The README does not state whether there is a maximum duration, whether concurrent requests are serialized, or whether client cancellation changes server behavior.

The gRPC contract is represented by `grpc.proto`, while `grpc/` contains related generated code. The README's example calls `whoami.Whoami/Whoami` to retrieve a hostname and interface list, and `whoami.Whoami/Bench` to retrieve data containing `1`. It does not document how to start a gRPC-only process or provide a complete field-level guide, so engineers needing precise client behavior should inspect `grpc.proto`. The HTTP equivalent is better represented by `openapi.yaml`.

Changing and Observing the whoami Health Response

The `/health` path can simulate an unsuccessful response, which is useful when testing a proxy's handling of upstream errors. A `POST` changes the status returned by later requests. The first command sends the body `500`, and the second performs a verbose `GET`.

This `POST` requests a `500` health response from the running container.

curl -X POST -d '500' http://localhost:8080/health

The following request should receive `HTTP/1.1 500 Internal Server Error`, as shown in the README.

This verbose request displays the status line and response headers returned by `/health`.

curl -v http://localhost:8080/health

The README documents that `GET`, `HEAD`, and other methods use the status established through `POST`. It does not document authentication, per-client isolation, locking, a timeout, a reset endpoint, or the original default status. Consequently, any client that can reach this endpoint and knows the documented method can potentially change the response observed by other clients.

That makes `/health` suitable for a controlled proxy fixture, not for a production readiness check. Engineers should keep the container on a trusted test network or restrict access through their own proxy policy. The endpoint can verify whether a `500` propagates. It does not independently diagnose whether the cause came from the application, proxy, network, or selected upstream.

Configuring TLS Files for whoami Mutual Authentication

whoami exposes three certificate-related command-line flags: `cert`, `key`, and `cacert`. The `cacert` description says that supplying a CA chain enforces mutual TLS. The README's full example generates a self-signed certificate and key, mounts the directory at `/certs`, and passes the certificate paths after the container image name.

This OpenSSL command creates the documented test certificate and private key under `./certs`.

openssl req -newkey rsa:4096 \
    -x509 \
    -sha256 \
    -days 3650 \
    -nodes \
    -out ./certs/example.crt \
    -keyout ./certs/example.key

The next command starts the container with the generated certificate and key. It mounts the complete local `certs` directory at `/certs` and continues to publish container port `80` on host port `8080`.

This command supplies the mounted certificate and key paths to whoami.

docker run -d -p 8080:80 -v ./certs:/certs --name iamfoo traefik/whoami --cert /certs/example.crt --key /certs/example.key

The documented client request uses `curl -k`, which disables normal verification of the server certificate. It also supplies the same certificate and private key as a client certificate.

This request demonstrates HTTPS access while accepting the test server certificate and presenting client credentials.

curl https://localhost:8080 -k --cert certs/example.crt --key certs/example.key

This example should not be copied into a production trust model. `-k` bypasses server certificate verification, and the generated key is stored in the working directory. The README does not document certificate rotation, file reload behavior, cipher-suite policy, access-log redaction, or renewal. Those gaps matter when deciding whether whoami should remain a permanent TLS test service.

Payload, Delay, and Environment Endpoints in whoami

The `/data` endpoint creates a response with a size supplied through `size`. An optional `unit` accepts `KB`, `MB`, `GB`, or `TB`; when omitted, the default unit is bytes. This path is useful for sending controlled response bodies through a proxy or inspecting transfer behavior. It does not establish throughput because the README provides no concurrency procedure, client configuration, timing method, or benchmark result.

The fixed `/bench` route always returns the same response, `1`. Calling that route “bench” should not be confused with a formal benchmarking suite. Its documented behavior makes it predictable for a basic response check. The more useful `/data` endpoint is for explicit response sizes, while the root endpoint's `wait` query parameter adds a controlled delay using Go duration syntax.

The `env=true` option works on the root and `/api` paths according to the README. It can help verify configuration passed to a container, but it turns a routing diagnostic into a potential configuration disclosure. Values such as connection strings, credentials, tokens, or internal addresses could be stored as environment variables. The README does not say which variables are included, whether values are masked, or how access is restricted.

The flags table adds two documented environment mappings. `WHOAMI_PORT_NUMBER` corresponds to `port`, whose default is `80`, and `WHOAMI_NAME` corresponds to `name`. There are no documented environment variable names for `cert`, `key`, `cacert`, or `verbose`. The repository's scratch-based runtime image also means diagnostics must come from whoami's supported endpoints or Docker's own logs rather than from a shell installed into the container.

Container Build, License, and Upgrade Considerations

The `Dockerfile` uses a multi-stage build. Its builder starts from `golang:1-alpine`, installs Git, CA certificates, time zone data, and Make, downloads modules from `go.mod` and `go.sum`, then runs `make build`. The final stage uses `scratch`, copies the static binary as `/whoami`, copies time zone and CA certificate data, and exposes port `80`.

A scratch runtime reduces the number of operating-system components in the image. It also means the running container has no documented shell or package manager. That is appropriate for a short-lived diagnostic backend, but it limits inspection options. The runtime must rely on the behavior built into the binary and on container-level tools outside the image.

The Makefile separates build, test, lint, and image targets. The build uses a static configuration with CGO disabled. The test target runs Go tests with coverage, while the check target requires `golangci-lint` to be installed separately. The README does not document a source-build first use, and the `go.mod` requirement for Go `1.26.0` should be checked before local compilation.

The repository is not archived. Its last push was on 2026-07-29, and version `v1.12.0` was released on 2026-07-30. The README does not provide a support policy, release compatibility matrix, or migration guide, so an upgrade should be reviewed tag by tag. Teams using whoami for proxy acceptance tests should rerun their HTTP, WebSocket, gRPC, TLS, delay, and health-status cases after changing versions.

The repository uses the Apache-2.0 license. It supplies the license text in `LICENSE` and permits use and modification under that license's conditions, including applicable notice and distribution requirements. This review does not interpret those obligations. License permission does not make environment disclosure or mutable health state acceptable on an untrusted network.

Editorial conclusion

Adopt traefik/whoami for a disposable test backend when engineers need to inspect request routing, container networking, TLS behavior, WebSockets, gRPC calls, payload sizes, or propagated health statuses. Do not use it as a production application service or place diagnostic endpoints on an untrusted network without reviewing access controls, especially `/health` and requests using `env=true`. Verify the container image, exposed routes, TLS files, environment contents, and shared health status before starting the test.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. traefik/whoami on GitHub