ApacheOIDC/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Docker image: Apache HTTPD acting as a reverse proxy with OpenID Connect authentication, built on Ubuntu 20.04 using mod_auth_openidc. There is no application code, build system, or test suite — the repository is the Dockerfile plus the Apache configuration files baked into the image. Work here means editing config and the Dockerfile, then rebuilding the image.

Build & run

# Build locally
docker build -t apacheoidc .

# Run (override env vars to point at your OIDC provider / backend)
docker run -p 80:80 -p 443:443 \
  -e SERVER_NAME=localhost \
  -e OIDC_PROVIDER_URL=http://id.example.ch \
  apacheoidc

Multi-platform CI builds (linux/arm64,linux/amd64) run via docker buildx and push to a Gitea registry. The pipeline is defined in .gitea/workflows/docker.yml (active, triggers on push to main). .space.kts is a legacy JetBrains Space pipeline kept for reference.

Architecture & configuration

• Dockerfile — Installs Apache + libapache2-mod-auth-openidc, enables modules (auth_openidc, proxy, proxy_http, proxy_http2, proxy_wstunnel, ssl, rewrite, headers, …), and defines all runtime configuration as ENV variables. The OIDC_* / KC_* env vars and SERVER_NAME are the primary knobs for a deployment; they are meant to be overridden at docker run time, not edited in the image.
• apache2.conf — Main server config: security headers (HttpOnly/Secure cookies, X-Frame-Options, HSTS-style settings), OIDCCacheType file cache setup, logging to stdout/stderr, and IncludeOptional sites-enabled/* for vhosts.
• ssl.conf — Copied over mods-enabled/ssl.conf; defines TLS protocols/ciphers (TLS, SSLv3 disabled) and session cache.
• httpd-foreground — Container entrypoint; runs apache2 -DFOREGROUND.
• /config/{global.d,vhost-80.d,vhost-443.d} and sites-enabled — Directories created in the image for the actual reverse-proxy vhost definitions. These are not committed; the concrete proxy/OIDC vhost config is expected to be mounted in at runtime. The default 000-default.conf is removed during build.
• index.html — Placeholder landing page served at /var/www/html/app after login.

Important notes

• The OIDC_CLIENT_SECRET, OIDC_CRYPTO_PASSPHRASE, and similar values in the Dockerfile are development defaults only — always override them in real deployments.
• LogLevel debug (in apache2.conf) and APACHE_DEBUG_LEVEL log OIDC tokens. As the Dockerfile comment warns, debug logging must never be used in production.
• STOPSIGNAL WINCH is used for Apache graceful stop.