From d8cc2d80b6cf26034302a2fb447f5c7775fd9439 Mon Sep 17 00:00:00 2001 From: Julien Cabillot Date: Mon, 8 Jun 2026 11:07:14 -0400 Subject: [PATCH 1/7] feat: add AGENTS.md --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6af1cd7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,30 @@ +# 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 Apache. + - `index.php`: Single endpoint returning `REMOTE_ADDR` as JSON. +- `.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`: Multi-stage build extending `jcabillot/phpapache` base image, copies `root/` into `/var/www/html`. +- `.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` uses `ARG VERSION="latest"` to allow version pinning at build time, extends `jcabillot/phpapache` which provides PHP + Apache pre-configured. Application code is layered on top via `COPY root /var/www/html`. +- **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. -- 2.52.0 From d5fc87f67b945746b08d537ee1395e324e7e3397 Mon Sep 17 00:00:00 2001 From: Julien Cabillot Date: Mon, 8 Jun 2026 11:34:24 -0400 Subject: [PATCH 2/7] feat: add integration tests and hadolint to CI pipeline --- .gitea/workflows/docker-build.yaml | 80 ++++++++++++++++++++++-------- tests/test.sh | 72 +++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 22 deletions(-) create mode 100755 tests/test.sh diff --git a/.gitea/workflows/docker-build.yaml b/.gitea/workflows/docker-build.yaml index 0a2f2cd..e4edc04 100644 --- a/.gitea/workflows/docker-build.yaml +++ b/.gitea/workflows/docker-build.yaml @@ -9,38 +9,74 @@ on: - cron: '0 0 * * *' jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Hadolint + uses: hadolint/hadolint-action@v3.1.0 + with: + dockerfile: Dockerfile + build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v6 - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v4 + - name: Build image + run: docker build -t ci-image:${{ github.sha }} . + + - name: Save image + run: docker save -o image.tar ci-image:${{ github.sha }} + + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: docker-image + path: image.tar + retention-days: 1 + + test: + runs-on: ubuntu-latest + needs: [lint, build] + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Download artifact + uses: actions/download-artifact@v4 + with: + name: docker-image + + - name: Load image + run: docker load < image.tar + + - name: Run tests + run: bash tests/test.sh ci-image:${{ github.sha }} + + push: + runs-on: ubuntu-latest + needs: test + if: github.event_name != 'pull_request' + steps: + - name: Download artifact + uses: actions/download-artifact@v4 + with: + name: docker-image + + - name: Load image + run: docker load < image.tar - name: Login to Docker Hub - if: github.event_name != 'pull_request' uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - name: Docker metadata - id: meta - uses: docker/metadata-action@v6 - with: - images: jcabillot/ip - tags: | - #type=ref,event=branch - #type=ref,event=pr - #type=sha - type=raw,value=latest,enable=${{ github.ref == 'refs/heads/master' }} - - - name: Build and push - uses: docker/build-push-action@v7 - with: - context: . - push: ${{ github.event_name != 'pull_request' }} - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - pull: true + - name: Tag and push + run: | + docker tag ci-image:${{ github.sha }} jcabillot/ip:latest + docker push jcabillot/ip:latest diff --git a/tests/test.sh b/tests/test.sh new file mode 100755 index 0000000..8e84e47 --- /dev/null +++ b/tests/test.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail + +IMAGE="${1:?Usage: test.sh }" +CONTAINER_NAME="test-$(basename "$IMAGE")-$$" +PASSED=0 +FAILED=0 +TOTAL=0 + +cleanup() { + docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true +} +trap cleanup EXIT + +assert() { + local name="$1" expected="$2" actual="$3" + TOTAL=$((TOTAL + 1)) + if [ "$expected" = "$actual" ]; then + echo " PASS: $name" + PASSED=$((PASSED + 1)) + else + echo " FAIL: $name (expected: '$expected', got: '$actual')" + FAILED=$((FAILED + 1)) + fi +} + +assert_match() { + local name="$1" pattern="$2" actual="$3" + TOTAL=$((TOTAL + 1)) + if echo "$actual" | grep -qE "$pattern"; then + echo " PASS: $name" + PASSED=$((PASSED + 1)) + else + echo " FAIL: $name (pattern: '$pattern', got: '$actual')" + FAILED=$((FAILED + 1)) + fi +} + +echo "Running container: $IMAGE" +docker run -d --name "$CONTAINER_NAME" -p 0:8080 "$IMAGE" >/dev/null + +HOST_PORT=$(docker port "$CONTAINER_NAME" 8080/tcp | head -1 | cut -d: -f2) +BASE_URL="http://127.0.0.1:${HOST_PORT}" + +echo "Waiting for container (port $HOST_PORT)..." +for i in $(seq 1 30); do + if curl -sf "$BASE_URL/" >/dev/null 2>&1; then + echo "Container ready after ${i}s" + break + fi + if [ "$i" -eq 30 ]; then + echo "FAIL: Container did not become ready within 30s" + docker logs "$CONTAINER_NAME" + exit 1 + fi + sleep 1 +done + +echo "" +echo "Test: GET /" +RESPONSE=$(curl -sf -D - "$BASE_URL/") +STATUS=$(echo "$RESPONSE" | head -1 | grep -oP '\d{3}') +CONTENT_TYPE=$(echo "$RESPONSE" | grep -i 'content-type' | tr -d '\r' | cut -d: -f2- | xargs) +BODY=$(echo "$RESPONSE" | tail -1) + +assert "HTTP status is 200" "200" "$STATUS" +assert_match "Content-Type is application/json" "application/json" "$CONTENT_TYPE" +assert_match "Body contains valid IP" '^(\"[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+\"|\"[0-9a-fA-F:]+\")$' "$BODY" + +echo "" +echo "Results: $PASSED/$TOTAL passed, $FAILED failed" +[ "$FAILED" -eq 0 ] -- 2.52.0 From e858cb9646ef1a857d64da82e6aa1b8590cb7c89 Mon Sep 17 00:00:00 2001 From: Sagent Date: Mon, 8 Jun 2026 16:25:59 +0000 Subject: [PATCH 3/7] fix: pin actions to SHA and use Gitea-compatible artifact actions - Pin all actions to commit SHAs for supply chain security - Replace actions/upload-artifact@v4 with ChristopherHX/gitea-upload-artifact - Replace actions/download-artifact@v4 with ChristopherHX/gitea-download-artifact - These forks work on Gitea Actions (GHES-compatible) --- .gitea/workflows/docker-build.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.gitea/workflows/docker-build.yaml b/.gitea/workflows/docker-build.yaml index e4edc04..c7fe0fb 100644 --- a/.gitea/workflows/docker-build.yaml +++ b/.gitea/workflows/docker-build.yaml @@ -13,10 +13,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 - name: Hadolint - uses: hadolint/hadolint-action@v3.1.0 + uses: hadolint/hadolint-action@54c9adbab1582c2ef04b2016b760714a4bfde3cf # v3.1.0 with: dockerfile: Dockerfile @@ -24,7 +24,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 - name: Build image run: docker build -t ci-image:${{ github.sha }} . @@ -33,7 +33,7 @@ jobs: run: docker save -o image.tar ci-image:${{ github.sha }} - name: Upload artifact - uses: actions/upload-artifact@v4 + uses: https://github.com/ChristopherHX/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2 # main with: name: docker-image path: image.tar @@ -44,10 +44,10 @@ jobs: needs: [lint, build] steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 - name: Download artifact - uses: actions/download-artifact@v4 + uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7 # main with: name: docker-image @@ -63,7 +63,7 @@ jobs: if: github.event_name != 'pull_request' steps: - name: Download artifact - uses: actions/download-artifact@v4 + uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7 # main with: name: docker-image @@ -71,7 +71,7 @@ jobs: run: docker load < image.tar - name: Login to Docker Hub - uses: docker/login-action@v4 + uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} -- 2.52.0 From 97ccaee674d865ac651438fbef276e4ccadf30f6 Mon Sep 17 00:00:00 2001 From: Sagent Date: Mon, 8 Jun 2026 16:33:31 +0000 Subject: [PATCH 4/7] fix: sanitize container name in test script Replace : and / with - to comply with Docker container naming rules. The colon in image:tag format is invalid in container names. --- tests/test.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test.sh b/tests/test.sh index 8e84e47..6a7d4d0 100755 --- a/tests/test.sh +++ b/tests/test.sh @@ -2,7 +2,7 @@ set -euo pipefail IMAGE="${1:?Usage: test.sh }" -CONTAINER_NAME="test-$(basename "$IMAGE")-$$" +CONTAINER_NAME="test-$(echo "$IMAGE" | tr ':/' '-')-$$" PASSED=0 FAILED=0 TOTAL=0 -- 2.52.0 From 268d8d2b62039d247f74e58d64845edbb1f7f361 Mon Sep 17 00:00:00 2001 From: Sagent Date: Mon, 8 Jun 2026 16:46:13 +0000 Subject: [PATCH 5/7] fix: use container IP instead of port mapping for health check When running inside Gitea Actions runner (Docker-in-Docker), 127.0.0.1:HOST_PORT doesn't work because the runner container doesn't have access to the host's port mappings. Use docker inspect to get the container's direct IP address. --- tests/test.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/test.sh b/tests/test.sh index 6a7d4d0..83e9e8f 100755 --- a/tests/test.sh +++ b/tests/test.sh @@ -39,10 +39,10 @@ assert_match() { echo "Running container: $IMAGE" docker run -d --name "$CONTAINER_NAME" -p 0:8080 "$IMAGE" >/dev/null -HOST_PORT=$(docker port "$CONTAINER_NAME" 8080/tcp | head -1 | cut -d: -f2) -BASE_URL="http://127.0.0.1:${HOST_PORT}" +CONTAINER_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$CONTAINER_NAME") +BASE_URL="http://${CONTAINER_IP}:8080" -echo "Waiting for container (port $HOST_PORT)..." +echo "Waiting for container (ip $CONTAINER_IP)..." for i in $(seq 1 30); do if curl -sf "$BASE_URL/" >/dev/null 2>&1; then echo "Container ready after ${i}s" -- 2.52.0 From 9da0efa29c9dbcb5c13cb8a9c9a4b8e5cd46b2a6 Mon Sep 17 00:00:00 2001 From: Sagent Date: Mon, 8 Jun 2026 17:57:50 +0000 Subject: [PATCH 6/7] fix(test): use --network=host for Docker-in-Docker compatibility --- tests/test.sh | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/tests/test.sh b/tests/test.sh index 83e9e8f..ddcca66 100755 --- a/tests/test.sh +++ b/tests/test.sh @@ -37,12 +37,11 @@ assert_match() { } echo "Running container: $IMAGE" -docker run -d --name "$CONTAINER_NAME" -p 0:8080 "$IMAGE" >/dev/null +docker run -d --name "$CONTAINER_NAME" --network=host "$IMAGE" >/dev/null -CONTAINER_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$CONTAINER_NAME") -BASE_URL="http://${CONTAINER_IP}:8080" +BASE_URL="http://localhost:8080" -echo "Waiting for container (ip $CONTAINER_IP)..." +echo "Waiting for container on localhost:8080..." for i in $(seq 1 30); do if curl -sf "$BASE_URL/" >/dev/null 2>&1; then echo "Container ready after ${i}s" -- 2.52.0 From 690859448e231edc3d92d85d52c939ab832c6fce Mon Sep 17 00:00:00 2001 From: Sagent Date: Mon, 8 Jun 2026 18:19:35 +0000 Subject: [PATCH 7/7] fix(test): use Docker bridge gateway for DinD networking --- tests/test.sh | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tests/test.sh b/tests/test.sh index ddcca66..8159289 100755 --- a/tests/test.sh +++ b/tests/test.sh @@ -37,11 +37,12 @@ assert_match() { } echo "Running container: $IMAGE" -docker run -d --name "$CONTAINER_NAME" --network=host "$IMAGE" >/dev/null +docker run -d --name "$CONTAINER_NAME" -p 8080:8080 "$IMAGE" >/dev/null -BASE_URL="http://localhost:8080" +DOCKER_GW=$(docker network inspect bridge --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}') +BASE_URL="http://${DOCKER_GW}:8080" -echo "Waiting for container on localhost:8080..." +echo "Waiting for container on ${DOCKER_GW}:8080..." for i in $(seq 1 30); do if curl -sf "$BASE_URL/" >/dev/null 2>&1; then echo "Container ready after ${i}s" -- 2.52.0