ip/AGENTS.md

# AGENTS.md

## 1. Overview

Lightweight PHP micro-service that returns the client's public IP address as JSON. Containerized with Docker and deployed on Kubernetes.

## 2. Folder Structure

- `root/`: Application source code served by FrankenPHP/Caddy.
    - `index.php`: Single endpoint returning `REMOTE_ADDR` as JSON.
- `Caddyfile`: FrankenPHP/Caddy web server configuration — PHP handler on `:8080` with `try_files` + `php_server`.
- `.gitea/workflows/`: Gitea Actions CI pipelines.
    - `docker-build.yaml`: Build and push Docker image to Docker Hub on push/PR to master + daily cron.
- `Dockerfile`: Single-stage build from `dunglas/frankenphp:1-php8.5-alpine`, copies `root/` into `/app/public`.
- `.gitlab-ci.yml`: Legacy GitLab CI config (deprecated, replaced by Gitea Actions).
- `Jenkinsfile`: Legacy Jenkins pipeline (deprecated, replaced by Gitea Actions).

## 3. Core Behaviors & Patterns

- **Request/Response Flow**: Single PHP endpoint sets `Content-Type: application/json` header and returns `$_SERVER['REMOTE_ADDR']` encoded as JSON string. No routing, no framework, no state.
- **Container Base Image Pattern**: `Dockerfile` is a single-stage build from a fixed `dunglas/frankenphp:1-php8.5-alpine` tag (Alpine-based FrankenPHP with Caddy). No `ARG VERSION` — the tag is pinned, Renovate auto-detects it. Application code is layered via `COPY root /app/public`. FrankenPHP provides PHP + Caddy pre-configured.
- **Traefik IngressRoute with HTTPS Redirect**: Two IngressRoute resources handle traffic — `ip-websecure` serves HTTPS on the `websecure` entrypoint, `ip-web` catches HTTP on `web` entrypoint and applies a `redirectScheme` middleware for permanent HTTPS redirect. The Service reference in the HTTP IngressRoute is required by Traefik even though the middleware intercepts before reaching it.
- **Health Probes**: Deployment defines both `livenessProbe` and `readinessProbe` using `httpGet` on `/` at the named `http` port (8080). Kubernetes uses these to restart unhealthy pods and exclude unready pods from the Service endpoints.
- **Security Hardening**: Pod spec sets `automountServiceAccountToken: false` to prevent unnecessary Kubernetes API access from the container.

## 4. Conventions

- **Kubernetes Labels**: Pods use `app: "front"` for Service selector matching and `owner: "jcabillot"` for resource attribution. Deployment-level labels use `app: "front"`.
- **Named Ports**: Container port is named `http` (8080) and referenced by name in probes and Service targetPort, avoiding hardcoded port numbers.
- **Docker Image Tagging**: CI uses `docker/metadata-action` to generate tags — `latest` for master branch pushes, branch/PR/SHA tags for other events. Push is skipped on pull requests.
- **CI Secrets**: Docker Hub credentials are stored as Gitea Actions secrets (`DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`), never hardcoded.