# 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

```bash
# 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](.gitea/workflows/docker.yml) (active, triggers on push to `main`). [.space.kts](.space.kts) is a legacy JetBrains Space pipeline kept for reference.

## Architecture & configuration

- **[Dockerfile](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](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](ssl.conf)** — Copied over `mods-enabled/ssl.conf`; defines TLS protocols/ciphers (TLS, SSLv3 disabled) and session cache.
- **[httpd-foreground](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](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.