Skip to content

README.md

Latest commit

 

History

History
120 lines (93 loc) · 5.28 KB

README.md

File metadata and controls

120 lines (93 loc) · 5.28 KB
Raw

reef-traefik-demo-app

A tiny demo container that runs both:

  1. the exact whoami binary from the traefik/whoami image, and
  2. its own Traefik instance reverse-proxying to it,

so you can reconfigure Traefik freely for demos without touching an external proxy.

             :8080 (host)                 :8081 (host)
                │                              │
        ┌───────▼──────────────────────────────▼───────┐
        │  container                                    │
        │   Traefik  :80 (web) ──▶ whoami 127.0.0.1:8000│
        │            :8080 (dashboard/API)              │
        └───────────────────────────────────────────────┘

Run

make up        # build + start in the background
make logs      # follow logs
make down      # stop

Then:

A request to :8080 that comes back with X-Forwarded-* headers confirms it traversed Traefik rather than hitting whoami directly:

curl -s localhost:8080/ | grep -i x-forwarded

Authentication (OIDC)

Traefik can enforce OIDC login in front of whoami using the lukaszraczylo/traefikoidc plugin (declared in traefik/traefik.yml). Config comes from environment variables and is rendered into Traefik's dynamic config at container startup by entrypoint.sh.

cp env.example .env
# edit .env: set REEF_ISSUER, REEF_CLIENT_ID, REEF_CLIENT_SECRET
make up

Register the callback with reef as a redirect URI: http://localhost:8080/oauth2/callback.

Now unauthenticated requests are challenged:

curl -sI localhost:8080/          # 302 -> ${REEF_ISSUER}/authorize...

Open http://localhost:8080/ in a browser → reef login → back to whoami.

To demo the contrast, set OIDC_ENABLED=false in .env and make up again — whoami is served directly (200, no redirect).

Environment variables

Set in .env (see env.example); passed through by docker-compose.yml.

Var Default Meaning
OIDC_ENABLED true false serves whoami with no auth.
REEF_ISSUER — OIDC issuer URL (discovery at …/.well-known/openid-configuration). Required when enabled.
REEF_CLIENT_ID — OAuth client id from reef. Required when enabled.
REEF_CLIENT_SECRET — OAuth client secret from reef. Required when enabled.
OIDC_CALLBACK_URL /oauth2/callback Callback path Traefik handles (register the full URL with reef).
OIDC_LOGOUT_URL /oauth2/logout RP-initiated logout path.
OIDC_FORCE_HTTPS false Keep false for the local http:// demo.
OIDC_LOG_LEVEL info debug / info / error.
OIDC_SCOPES openid,profile,email Comma-separated OAuth scopes.
OIDC_EXCLUDED_URLS — Comma-separated paths that bypass auth.
OIDC_SESSION_ENCRYPTION_KEY auto Cookie key (≥32 bytes). Blank ⇒ generated once and persisted to the oidc-session-key volume so it survives restarts.
WHOAMI_PORT 8000 Internal port whoami listens on.
WHOAMI_NAME reef-traefik-demo Name whoami reports.

Gotchas

  • Plugin download: on first start Traefik fetches the plugin source from GitHub — the container needs network egress.
  • OIDC_FORCE_HTTPS must be false for the plain-http local demo, or the plugin builds https:// redirect/callback URLs that won't resolve.
  • Issuer reachability: the browser and the container must reach REEF_ISSUER at the same URL (the token iss must match). If reef runs on your host, use http://host.docker.internal:<port> and set reef's issuer to match — plain localhost means different things inside vs outside the container.
  • "Critical session error" (HTTP 500): the plugin can't decode a session cookie because the session key changed since the cookie was set, and it won't clear the bad cookie itself. To recover: clear cookies for localhost:8080 (or use a fresh/incognito window), then reload. The key is now persisted across restarts (oidc-session-key volume) so this shouldn't recur; if you rotate it deliberately (change OIDC_SESSION_ENCRYPTION_KEY, or docker compose down -v), clear cookies again.

Configure Traefik

  • Static config lives in traefik/traefik.yml (entrypoints, dashboard, the plugin declaration). It's bind-mounted; edits apply after make restart.
  • Dynamic config (router + service + OIDC middleware) is generated at startup by entrypoint.sh from the environment, so change behaviour via .env and re-run make up. To alter the routing structure itself, edit the heredoc in entrypoint.sh.

How it works

entrypoint.sh renders /etc/traefik/dynamic/dynamic.yml from the environment, starts whoami in the background, then execs Traefik in the foreground (so Traefik is PID 1 and shuts down cleanly on docker stop). The image is built by copying the whoami binary onto the official traefik base image — see Dockerfile.