chore: organize legacy images under v1

.github/workflows/build-fpm.yml → .github/workflows/build-v1-fpm.yml

@@ -1,32 +1,22 @@
-name: Build FPM Images
+name: Build v1 FPM Images
 on:
   workflow_dispatch:
   push:
     branches:
       - main
     paths:
-      - 'docker-bake.hcl'
-      - 'docker-bake.fpm.hcl'
-      - '.github/workflows/build-fpm.yml'
+      - 'v1/docker-bake.hcl'
+      - '.github/workflows/build-v1-fpm.yml'
       - '.github/action/build-bake-publish/**'
       - '.github/action/setup-builder/**'
-      - 'fpm/**'
-      - 'fpm-otel/**'
-      - 'caddy/**'
-      - 'nginx/**'
-      - 'dev/**'
+      - 'v1/fpm/**'
   pull_request:
     paths:
-      - 'docker-bake.hcl'
-      - 'docker-bake.fpm.hcl'
-      - '.github/workflows/build-fpm.yml'
+      - 'v1/docker-bake.hcl'
+      - '.github/workflows/build-v1-fpm.yml'
       - '.github/action/build-bake-publish/**'
       - '.github/action/setup-builder/**'
-      - 'fpm/**'
-      - 'fpm-otel/**'
-      - 'caddy/**'
-      - 'nginx/**'
-      - 'dev/**'
+      - 'v1/fpm/**'
   schedule:
     - cron: '10 4 * * *'
 
@@ -60,7 +50,7 @@ jobs:
       - name: Read PHP versions from Bake
         id: matrix
         run: |
-          matrix=$(docker buildx bake -f docker-bake.hcl -f docker-bake.fpm.hcl --print fpm | jq -c '{include: [.group.fpm.targets[] | ltrimstr("fpm-") | {php: gsub("-"; "."), suffix: .}]}')
+          matrix=$(docker buildx bake -f v1/docker-bake.hcl -f v1/fpm/docker-bake.hcl --print fpm | jq -c '{include: [.group.fpm.targets[] | ltrimstr("fpm-") | {php: gsub("-"; "."), suffix: .}]}')
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
 
   fpm:
@@ -85,26 +75,26 @@ jobs:
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.fpm.hcl
+            v1/docker-bake.hcl
+            v1/fpm/docker-bake.hcl
           targets: fpm-${{ matrix.suffix }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build FPM with OpenTelemetry
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.fpm.hcl
+            v1/docker-bake.hcl
+            v1/fpm/docker-bake.hcl
           targets: fpm-otel-${{ matrix.suffix }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build webserver images
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.fpm.hcl
+            v1/docker-bake.hcl
+            v1/fpm/docker-bake.hcl
           targets: |
             caddy-${{ matrix.suffix }}
             nginx-${{ matrix.suffix }}
@@ -114,8 +104,8 @@ jobs:
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.fpm.hcl
+            v1/docker-bake.hcl
+            v1/fpm/docker-bake.hcl
           targets: |
             caddy-otel-${{ matrix.suffix }}
             nginx-otel-${{ matrix.suffix }}
@@ -144,8 +134,8 @@ jobs:
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.fpm.hcl
+            v1/docker-bake.hcl
+            v1/fpm/docker-bake.hcl
           targets: ${{ matrix.webserver }}-dev
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
@@ -178,7 +168,7 @@ jobs:
         run: docker pull ${{ steps.image-tag.outputs.IMAGE_TAG }}
 
       - name: Test Dev Image
-        run: container-structure-test test --config dev/config.yaml --image ${{ steps.image-tag.outputs.IMAGE_TAG }}
+        run: container-structure-test test --config v1/fpm/dev/config.yaml --image ${{ steps.image-tag.outputs.IMAGE_TAG }}
 
   check:
     name: Test Image with Webserver ${{ matrix.webserver }}

.github/workflows/build-frankenphp.yml → .github/workflows/build-v1-frankenphp.yml

@@ -1,26 +1,22 @@
-name: Build FrankenPHP Images
+name: Build v1 FrankenPHP Images
 on:
   workflow_dispatch:
   push:
     branches:
       - main
     paths:
-      - 'docker-bake.hcl'
-      - 'docker-bake.frankenphp.hcl'
-      - '.github/workflows/build-frankenphp.yml'
+      - 'v1/docker-bake.hcl'
+      - '.github/workflows/build-v1-frankenphp.yml'
       - '.github/action/build-bake-publish/**'
       - '.github/action/setup-builder/**'
-      - 'frankenphp/**'
-      - 'frankenphp-otel/**'
+      - 'v1/frankenphp/**'
   pull_request:
     paths:
-      - 'docker-bake.hcl'
-      - 'docker-bake.frankenphp.hcl'
-      - '.github/workflows/build-frankenphp.yml'
+      - 'v1/docker-bake.hcl'
+      - '.github/workflows/build-v1-frankenphp.yml'
       - '.github/action/build-bake-publish/**'
       - '.github/action/setup-builder/**'
-      - 'frankenphp/**'
-      - 'frankenphp-otel/**'
+      - 'v1/frankenphp/**'
   schedule:
     - cron: '10 4 * * *'
 
@@ -54,7 +50,7 @@ jobs:
       - name: Read PHP versions from Bake
         id: matrix
         run: |
-          matrix=$(docker buildx bake -f docker-bake.hcl -f docker-bake.frankenphp.hcl --print frankenphp | jq -c '{include: [.group.frankenphp.targets[] | ltrimstr("frankenphp-") | {php: gsub("-"; "."), suffix: .}]}')
+          matrix=$(docker buildx bake -f v1/docker-bake.hcl -f v1/frankenphp/docker-bake.hcl --print frankenphp | jq -c '{include: [.group.frankenphp.targets[] | ltrimstr("frankenphp-") | {php: gsub("-"; "."), suffix: .}]}')
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
 
   frankenphp:
@@ -79,16 +75,16 @@ jobs:
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.frankenphp.hcl
+            v1/docker-bake.hcl
+            v1/frankenphp/docker-bake.hcl
           targets: frankenphp-${{ matrix.suffix }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build FrankenPHP with OpenTelemetry
         uses: ./.github/action/build-bake-publish
         with:
           files: |
-            docker-bake.hcl
-            docker-bake.frankenphp.hcl
+            v1/docker-bake.hcl
+            v1/frankenphp/docker-bake.hcl
           targets: frankenphp-otel-${{ matrix.suffix }}
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/security.yml

@@ -22,21 +22,21 @@ jobs:
           - '8.5'
         variant:
           - name: fpm
-            dockerfile: fpm/Dockerfile
+            dockerfile: v1/fpm/Dockerfile
           - name: fpm-otel
-            dockerfile: fpm-otel/Dockerfile
+            dockerfile: v1/fpm/otel/Dockerfile
           - name: caddy
-            dockerfile: caddy/Dockerfile
+            dockerfile: v1/fpm/caddy/Dockerfile
           - name: caddy-otel
-            dockerfile: caddy/Dockerfile
+            dockerfile: v1/fpm/caddy/Dockerfile
           - name: nginx
-            dockerfile: nginx/Dockerfile
+            dockerfile: v1/fpm/nginx/Dockerfile
           - name: nginx-otel
-            dockerfile: nginx/Dockerfile
+            dockerfile: v1/fpm/nginx/Dockerfile
           - name: frankenphp
-            dockerfile: frankenphp/Dockerfile
+            dockerfile: v1/frankenphp/Dockerfile
           - name: frankenphp-otel
-            dockerfile: frankenphp-otel/Dockerfile
+            dockerfile: v1/frankenphp/otel/Dockerfile
     steps:
       - name: Checkout
         uses: actions/checkout@v7

.github/workflows/update-php-matrix.yml

@@ -27,7 +27,7 @@ jobs:
           token: ${{ steps.generate-token.outputs.token }}
 
       - name: Run PHP matrix update script
-        run: node update-php-matrix.mjs
+        run: node scripts/update-php-matrix.mjs
 
       - name: Check for changes
         id: changes
@@ -52,8 +52,8 @@ jobs:
             This PR automatically updates the PHP matrix versions to the latest patch releases.
 
             The family-specific Bake files have been updated:
-            - `docker-bake.fpm.hcl`: Supported PHP patch versions
-            - `docker-bake.frankenphp.hcl`: Supported FrankenPHP patch versions
+            - `v1/fpm/docker-bake.hcl`: Supported PHP patch versions
+            - `v1/frankenphp/docker-bake.hcl`: Supported FrankenPHP patch versions
 
             Changes were detected by the automated PHP matrix update workflow.
 

README.md

@@ -6,15 +6,43 @@ This repository contains a base image with Alpine + PHP + (Caddy or Nginx), whic
 
 The Nginx, Caddy and FrankenPHP configurations send `script-src 'none'; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'` for static SVG files and existing HTML files under `public/media` and `public/thumbnail`. Application-rendered HTML and bundled HTML applications retain their own response policies. Custom static documents must work without scripts, embedded documents, base URL overrides or form submissions; images and styles remain permitted. Development images inherit the corresponding server configuration.
 
+## Repository layout
+
+Image generations live in their own top-level directories. The existing images
+live in `v1/`; future calendar versions, such as `v2026.1/`, can coexist alongside
+them with their own build definitions and configuration.
+
+```text
+v1/
+├── docker-bake.hcl          # Shared v1 variables
+├── fpm/
+│   ├── docker-bake.hcl      # FPM and derived image targets
+│   ├── Dockerfile
+│   ├── rootfs/
+│   ├── otel/
+│   ├── caddy/
+│   ├── nginx/
+│   └── dev/                # Shared by the Caddy and Nginx dev images
+└── frankenphp/
+    ├── docker-bake.hcl
+    ├── Dockerfile
+    ├── rootfs/
+    └── otel/
+```
+
+Shared automation lives in `.github/` and `scripts/`. The directory names do not
+change the published image tags: v1 images keep their existing unversioned tags.
+
 ## Building images
 
-Bake settings are split into shared variables in `docker-bake.hcl` and targets
-in `docker-bake.fpm.hcl` and `docker-bake.frankenphp.hcl`. Load the shared file
-alongside the family you want to build:
+Bake settings are split into shared variables in `v1/docker-bake.hcl` and targets
+in `v1/fpm/docker-bake.hcl` and `v1/frankenphp/docker-bake.hcl`. Load the shared file
+alongside the family you want to build. Run these commands from the repository
+root, since Bake resolves build contexts relative to the working directory:
 
 ```sh
-docker buildx bake -f docker-bake.hcl -f docker-bake.fpm.hcl fpm
-docker buildx bake -f docker-bake.hcl -f docker-bake.frankenphp.hcl frankenphp
+docker buildx bake -f v1/docker-bake.hcl -f v1/fpm/docker-bake.hcl fpm
+docker buildx bake -f v1/docker-bake.hcl -f v1/frankenphp/docker-bake.hcl frankenphp
 ```
 
 FPM targets include `fpm`, `fpm-otel`, `caddy`, `caddy-otel`, `nginx`,
@@ -27,3 +55,6 @@ push it before building its dependents, as the CI workflows do.
 The FPM and FrankenPHP workflows build independently when their files change.
 Changes to shared Bake settings or the publishing action trigger both families.
 Both workflows also support manual runs and daily rebuilds.
+
+Run `node scripts/update-php-matrix.mjs` from the repository root to update the
+PHP patch versions in the family-specific Bake files.

update-php-matrix.mjs → scripts/update-php-matrix.mjs

@@ -78,8 +78,8 @@ function getLatestFrankenphpPatchVersion(apiResponse) {
 // Function to update the PHP matrices in the family-specific Bake files
 async function updatePhpMatrixInHcl(phpVersions, frankenphpVersions) {
     const updates = [
-        ['docker-bake.fpm.hcl', 'phpMatrix', phpVersions],
-        ['docker-bake.frankenphp.hcl', 'frankenphpMatrix', frankenphpVersions],
+        ['v1/fpm/docker-bake.hcl', 'phpMatrix', phpVersions],
+        ['v1/frankenphp/docker-bake.hcl', 'frankenphpMatrix', frankenphpVersions],
     ];
 
     for (const [hclPath, name, versions] of updates) {

docker-bake.hcl → v1/docker-bake.hcl

@@ -1,4 +1,4 @@
-# Shared settings; load with docker-bake.fpm.hcl or docker-bake.frankenphp.hcl.
+# Shared settings; load with v1/fpm/docker-bake.hcl or v1/frankenphp/docker-bake.hcl.
 
 variable "imageSuffix" {
     default = ""