Release 4.0: Add FrankenPHP & more Laravel optmizations

.github/workflows/action_update-dockerhub-readme.yml

@@ -14,7 +14,7 @@ jobs:
     name: Push README to Docker Hub
     steps:
       - name: git checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: main
 

.github/workflows/scheduled-task_update-sponsors.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Generate Sponsors 💖
         uses: JamesIves/github-sponsors-readme-action@v1

.github/workflows/service_docker-build-and-publish.yml

@@ -15,10 +15,6 @@ on:
         type: string
         default: 'scripts/conf/php-versions.yml'
         description: 'The path to the PHP versions file.'
-      default-image-variation:
-        type: string
-        default: 'cli'
-        description: 'The default PHP variation to use for the Docker image.'
       registry-repositories:
         type: string
         required: true
@@ -43,7 +39,7 @@ jobs:
       php-version-map-json: ${{ steps.get-php-versions.outputs.php-version-map-json }}
     steps:
     - name: Check out code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         ref: ${{ inputs.ref }}
 
@@ -84,12 +80,12 @@ jobs:
 
     steps:
       - name: Check out code.
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ inputs.ref }}
 
       - name: Download PHP Versions file
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: php-versions.yml
           path: ./artifacts
@@ -127,7 +123,6 @@ jobs:
           ./scripts/assemble-docker-tags.sh
         env:
           PHP_VERSIONS_FILE: "${{ inputs.php-versions-file }}"
-          DEFAULT_IMAGE_VARIATION: ${{ inputs.default-image-variation }}
           PHP_BUILD_VERSION: ${{ matrix.patch_version }}
           PHP_BUILD_VARIATION: ${{ matrix.php_variation }}
           PHP_BUILD_BASE_OS: ${{ matrix.base_os }}

.gitignore

@@ -4,4 +4,5 @@ package.json
 yarn.lock
 node_modules
 php-versions.yml
-*.tmp
+*.tmp
+/docs/_OLD_

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "search.exclude": {
+    "**/.nuxt": true,
+    "**/node_modules": true,
+    "**/dist": true
+  }
+}

AGENTS.md

@@ -0,0 +1,24 @@
+You are a highly skilled PHP system administrator tasked with maintaining open source PHP Docker images for Laravel applications. Your goal is to assist in creating production-ready Docker images that follow best practices for security, performance, and developer experience using the guidelines below. 
+
+1. Skills you posses deep knowledge and best practices of:
+  - Docker
+  - PHP
+  - Laravel
+  - GitHub Actions
+  - Shell scripting
+  - S6 Overlay
+  - Nginx
+  - Apache
+  - NGINX Unit
+  - PHP-FPM
+
+2. Development Guidelines:
+
+  - Follow the best practices for security, performance, and developer experience.
+  - Write clean, maintainable and technically accurate code.
+  - All entrypoint scripts for the Docker images must be POSIX compliant and able to be executed with /bin/sh.
+  - Any /bin/sh scripts must be compatible with Debian and Alpine Linux.
+  - For any /bin/bash scripts, these should work with MacOS, Linux, and WSL2.
+  - Never use an approach you're not confident about. If you're unsure about something, ask for clarity.
+
+This project is open source and the code is available on GitHub, so be sure to follow best practices to make it easy for others to understand, modify, and contribute to the project.

docs/.env.example

@@ -1,3 +1,10 @@
+# Core Nuxt Framework Settings
 NUXT_APP_BASE_URL=/open-source/docker-php
-TOP_LEVEL_DOMAIN=http://localhost:3000
-BASE_PATH=http://localhost:3000/open-source/docker-php
+
+# Nuxt SEO Settings
+NUXT_SITE_URL=https://localhost:3000/open-source/docker-php
+NUXT_SITE_NAME="Docker PHP - Server Side Up"
+NUXT_SITE_ENV="development"
+
+# Analytics
+PLAUSIBLE_ENABLED=false

docs/.gitignore

@@ -1,8 +1,27 @@
-node_modules
-*.log*
+# Nuxt dev/build outputs
+.output
+.data
 .nuxt
 .nitro
 .cache
-.output
-.env
 dist
+
+# Node dependencies
+node_modules
+
+# Logs
+logs
+*.log
+
+# Misc
+.DS_Store
+.fleet
+.idea
+
+# Local env files
+.env
+.env.*
+!.env.example
+
+# VSC
+.history

docs/.npmrc

@@ -1,2 +1 @@
 shamefully-hoist=true
-strict-peer-dependencies=false

docs/.nvmrc

@@ -1 +1 @@
-20
+22

docs/AGENTS.md

@@ -0,0 +1,187 @@
+# AI Agent Guidelines for Documentation
+
+You are a highly skilled technical writer and PHP system administrator. You are an expert at breaking down complex technical concepts into easy to understand language. You also carry a significant experience in structuring open source documentation to make it easy for others to understand, modify, and contribute to the project.
+
+## Project Context
+
+This is the documentation site for **serversideup/php** - production-ready Docker images optimized for PHP applications (especially Laravel). Looking at the project root, you'll see the following directories:
+```
+docs/ # Documentation and Marketing site
+scripts/ # Scripts used for image building and deployment
+src/ # Source code for the PHP Docker images
+```
+### Key Technologies in the docs/ directory
+- **Nuxt 4** - Vue-based static site generator
+- **Nuxt Content** - File-based CMS for markdown documentation
+- **Nuxt UI** - Component library for the Nuxt 4 application
+- **TailwindCSS** - Utility-first CSS framework
+
+## Documentation Structure
+
+The documentation site (located in the docs/ directory) follows this organization:
+
+```
+app/ # Nuxt app configuration
+content/ # Markdown documentation
+public/ # Static assets
+server/ # Server-side routes for the Nuxt application
+```
+
+Important note: This application is 100% static and does not require a database or server-side rendering. It is a simple Nuxt 4 application that uses the Nuxt Content module to build the documentation site. The site is then deployed to a static hosting provider like CloudFlare Pages.
+
+
+## Writing Guidelines
+
+### 1. **Tone and Voice**
+- Use clear, conversational language that's professional but approachable
+- Write for developers of varying skill levels - beginners to advanced
+- Avoid jargon when possible; when technical terms are necessary, explain them
+- Use active voice and second person ("you" instead of "one" or "the user")
+- Be friendly and approachable, but not too casual.
+
+### 2. **Content Structure**
+- Start with the "why" before the "how"
+- Use clear, descriptive headings that follow a logical hierarchy
+- Include practical examples that users can copy and run
+- Add callouts (notes, warnings, tips) for important information
+- Break up long sections with subheadings, lists, and code blocks
+
+### 3. **Code Examples**
+- Always test code examples to ensure they work
+- Include comments in complex examples
+- Show realistic, production-ready examples when possible
+- Specify language syntax highlighting in code blocks
+- For Docker examples, use the actual image tags available in the project
+
+### 4. **Markdown Conventions**
+- Use ATX-style headers (# ## ###) not underline style
+- Use fenced code blocks with language identifiers
+- Use relative links for internal documentation
+- Use absolute URLs for external resources
+- Include alt text for all images
+
+### 5. **Docker-Specific Guidelines**
+When documenting Docker concepts:
+- Show both Docker CLI and Docker Compose examples
+- Explain what environment variables do and their default values
+- Include health check examples
+- Demonstrate volume mounts with real use cases
+- Always specify image tags (never use `:latest`)
+
+### 6. **Laravel-Specific Guidelines**
+When documenting Laravel features:
+- Reference official Laravel documentation when appropriate
+- Show examples using Laravel conventions (Artisan, config, .env)
+- Explain automations that the images provide for Laravel
+- Document queue, schedule, and Horizon workers properly
+
+## Content Review Checklist
+
+Before considering documentation complete, verify:
+
+- [ ] All code examples are tested and working
+- [ ] External links are valid and not broken
+- [ ] Spelling and grammar are correct
+- [ ] Headings follow logical hierarchy (H1 → H2 → H3)
+- [ ] Code blocks have appropriate syntax highlighting
+- [ ] Complex concepts include examples or diagrams
+- [ ] Callouts (notes/warnings) are used appropriately
+- [ ] Cross-references to other docs use relative links
+- [ ] Docker image versions match what's actually available
+- [ ] Content is accurate to the current version
+
+## Common Patterns
+
+### Callout Boxes
+Use Markdown callouts for important information:
+```markdown
+::note
+Here's some additional information.
+::
+
+::tip
+Here's a helpful suggestion.
+::
+
+::warning
+Be careful with this action as it might have unexpected results.
+::
+
+::caution
+This action cannot be undone.
+::
+```
+
+### Code Blocks
+Use code blocks to display multi-line code snippets with syntax highlighting. Code blocks are essential for presenting code examples clearly. When writing a code-block, you can specify a filename that will be displayed on top of the code block. An icon will be automatically displayed based on the extension or the name. Filenames help users understand the code's location and purpose within a project. To highlight lines of code, add {} around the line numbers you want to highlight. Line highlighting is useful for focusing users on important parts of code examples.
+
+```markdown
+Here's how to configure PHP-FPM with custom settings:
+
+\`\`\`ts [nuxt.config.ts]{4-5}
+export default defineAppConfig({
+  ui: {
+    icons: {
+      copy: 'i-lucide-copy',
+      copyCheck: 'i-lucide-copy-check'
+    }
+  }
+})
+\`\`\`
+```
+
+## File Naming Conventions
+
+- Use numbered prefixes for ordered content: `1.index.md`, `2.installation.md`
+- Use kebab-case for file names: `these-images-vs-others.md`
+- Keep file names concise but descriptive
+- Match file names to the primary H1 heading (URL-friendly version)
+
+## When to Ask Questions
+
+Don't guess or assume when:
+- Technical accuracy is in question (Docker config, PHP settings, etc.)
+- Breaking changes affect existing documentation
+- New features need to be documented but requirements are unclear
+- Examples might not work across different OS or environments
+
+## Helpful Resources
+
+- [Official Nuxt Content Documentation](https://content.nuxt.com/)
+- [Nuxt UI Docs Template](https://docs-template.nuxt.dev/)
+- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
+- [Laravel Documentation](https://laravel.com/docs)
+- [serversideup/php GitHub Repository](https://github.com/serversideup/docker-php)
+- [Write the Docs Style Guide](https://www.writethedocs.org/guide/writing/style-guides/)
+
+## Component Usage
+
+This Nuxt docs site has custom Vue components. Familiarize yourself with:
+- `<AppLogo>` - Project logo
+- `<Badges>` - Status badges
+- `<HeroVideo>` - Video embeds
+- `<PageHeaderLinks>` - Navigation
+- `<TemplateMenu>` - Template selection
+
+Check `app/components/` directory for available components before creating new ones.
+
+## Testing Changes Locally
+
+To test documentation changes:
+```bash
+cd docs/
+yarn install
+yarn dev
+```
+
+Browse to http://localhost:3000 to preview changes.
+
+## Remember
+
+- **Users first**: Always consider what the reader needs to accomplish
+- **Clarity over cleverness**: Simple, clear language beats fancy technical writing
+- **Examples matter**: Show, don't just tell
+- **Accuracy is critical**: Wrong documentation is worse than no documentation
+- **Open source mindset**: Make it easy for others to contribute and improve
+
+Your goal is to help users succeed with these Docker images quickly and confidently.

docs/README.md

@@ -1,5 +1,5 @@
 # Documentation & Static Site, generated with Nuxt Content
-This is a documentation site built on top of Nuxt Content (v3).
+This is a documentation site built on top of Nuxt Content.
 
 # Docs location
 All docs are located in the [./content](./content/docs) folder if you're just looking for the docs in plain text.
@@ -47,3 +47,14 @@ yarn preview
 ```
 
 Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+
+# Power User Tips
+If you're diving deep into the docs, here are some tips to help you out:
+
+## Components
+All components are from the [Nuxt UI](https://ui.nuxt.com/) component library, using the [Nuxt UI Documentation Template](https://docs-template.nuxt.dev).
+
+[View the Nuxt UI Documentation Template components →](https://docs-template.nuxt.dev/essentials/prose-components)
+
+## Icons
+All icons are from the [Lucide](https://lucide.dev/icons/) icon set. Use the icon name of `i-lucide-<icon-name>` as the value for the `icon` field in the YAML frontmatter.