Merge branch 'main' into setup-nightwatch-healthchecks

Author: jaydrogers

docs/content/docs/1.getting-started/1.index.md

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: 'serversideup/php is an alternate approach to the official Docker images provided by PHP. Compared to the defaults provided by the official PHP Docker images, the serversideup/php Docker images are optimized for more real-world and production use cases and an easier developer experience.'
+description: 'Production-ready PHP Docker images built on official PHP. Optimized for security, performance, and developer experience.'
 ---
 
 ::hero-video
@@ -13,7 +13,7 @@ src: https://docker-php-public-assets.serversideup.net/docker-demo.mp4
 
 :badges
 
-**serversideup/php** is a "batteries included" approach to the official Docker images provided by PHP. Compared to the defaults provided by the official PHP Docker images, the **serversideup/php** Docker images are optimized for more real-world and production use cases and give you an easier developer experience.
+**serversideup/php** takes the official PHP Docker images and adds everything you need for production: better security, performance optimizations, and a developer experience that just works.
 
 ## These images are very different from other PHP Docker Images
 ::u-page-grid
@@ -126,12 +126,12 @@ src: https://docker-php-public-assets.serversideup.net/docker-demo.mp4
   :::
 ::
 
-This is just an overview. See the full list of benefits and features below. 
+<br />
 
-:u-button{to="/docs/getting-started/these-images-vs-others" label="Read more about the advantages" aria-label="Read more about the advantages" size="md" color="primary" variant="outline"  trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}
+:u-button{to="/docs/getting-started/these-images-vs-others" label="See all advantages" aria-label="Read more about the advantages" size="md" color="primary" variant="outline"  trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}
 
-## Why should I use these PHP Docker Images?
+## Ready to get started?
 
-These images are production-ready and optimized for performance and security. We work hard to give you a "batteries included" experience so you can ship PHP with Docker as fast as possible. Click below to see a simple working example.
+Ship PHP applications faster with a production-ready setup that includes everything you need out of the box.
 
 :u-button{to="/docs/getting-started/installation" label="Installation" aria-label="Installation" size="md" color="primary" variant="outline"  trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}

…ent-and-production/1.container-basics.md …/1.getting-started/2.container-basics.mddocs/content/docs/4.deployment-and-production/1.container-basics.md renamed to docs/content/docs/1.getting-started/2.container-basics.md docs/content/docs/4.deployment-and-production/1.container-basics.md renamed to docs/content/docs/1.getting-started/2.container-basics.md

@@ -3,6 +3,28 @@ title: Container Basics
 description: 'Learn the basics of containers with PHP and how to use it to deploy your PHP applications.'
 ---
 
+## Why even care about containers?
+
+If you're new to Docker or containers, you might be wondering why you should containerize your application in the first place. The short answer: **containers let you run your application anywhere** — from your laptop to any cloud provider — with zero changes.
+
+Key benefits of containerization:
+- **Consistency** - Your app runs the same on Mac, Windows, Linux, and production
+- **Confidence** - Infrastructure as code means easier testing and rollbacks
+- **Freedom** - No vendor lock-in; migrate hosts with minimal effort
+- **Simplicity** - Scaling from 1 to 100 containers is straightforward
+
+There are some important terms to understand when working with containers:
+
+| Term | Definition |
+|------|------------|
+| Container | A running instance of an image. |
+| Image | A template for a container to start with (ie. `serversideup/php:8.4-frankenphp`). |
+| Tag | A specific version of an image (ie. `8.4-frankenphp`). |
+| Registry | A repository of images. This is where users can pull images from to start a container. This can be places like [Docker Hub](https://hub.docker.com/r/serversideup/php) or [GitHub Packages](https://github.com/serversideup/docker-php/pkgs/container/php). |
+| Volume | A directory on your host machine that is mounted into a container. This allows you to share files between your host machine and the container. |
+| Port | Ports are virtual numbers organizing network data traffic, directing it to the correct application on a device. If you want to expose traffic to work with `http://localhost`, you would map port `80` on your host machine to port `8080` on the container. |
+| Environment Variable | A variable that is set in the container's environment. This allows you to configure the container's behavior. |
+
 ## What are containers?
 Containers are isolated environments that can run on any host. They are a great way to package your application and all of its dependencies into a single unit that can be easily deployed to any environment.
 
@@ -52,7 +74,32 @@ This is why switching from PHP 8.3 to 8.4 in the installation guide was so fast
 Image tags like `8.3-fpm-nginx` and `8.4-frankenphp` aren't just version numbers — they describe the entire stack that's included in that image. The tag tells you the PHP version and which variation (web server stack) you're getting.
 ::
 
-## Key container concepts
+## Key concepts
+
+### Service names
+A **service** in Docker Compose is a named container definition. Think of it as a label for a specific part of your application — like your web server, database, or cache. Each service runs in its own container and can be managed independently.
+
+In your `compose.yml`, when you define a service called `php`, you're telling Docker Compose "this is my PHP application server." You can name it anything you want — we use `php` to keep it simple, but `web`, `app`, or `backend` would work just as well.
+
+```yml [compose.yml] {2}
+services:
+  php:
+    image: serversideup/php:8.4-fpm-nginx
+    ports:
+      - 80:8080
+```
+
+Whenever you run commands, you'll need to reference the service name you gave it.
+
+```bash [Terminal]
+docker compose run php php -v
+```
+
+If you named your service `app`, you would run the following command:
+
+```bash [Terminal]
+docker compose run app php -v
+```
 
 ### Volumes: Sharing files with containers
 When you added this to your `compose.yml`:
@@ -154,6 +201,6 @@ The `-f` flag in `docker compose logs -f` means "follow" — it keeps showing ne
 ::
 
 ## What's next?
-Now that you understand the fundamentals of containers, you're ready to learn how to take your application from development to production. Our next guide walks you through the entire journey, showing you how to package your application properly and deploy it with confidence.
+Now that you understand the fundamentals of containers, let's create your first containerized PHP project.
 
-:u-button{to="/docs/deployment-and-production/development-to-production" label="Development to Production Guide" aria-label="Development to Production Guide" size="md" color="primary" variant="outline" trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}
+:u-button{to="/docs/getting-started/installation" label="Create your first Docker PHP project" aria-label="Create your first Docker PHP project" size="md" color="primary" variant="outline" trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}

docs/content/docs/1.getting-started/3.installation.md

@@ -9,39 +9,11 @@ title: Installation
 `serversideup/php` is compatible with any container orchestrator that supports Docker images (Kubernetes, Docker Swarm, Docker Compose, HashiCorp Nomad, etc.). All images are hosted on [DockerHub](https://hub.docker.com/r/serversideup/php) and [GitHub Packages](https://github.com/serversideup/docker-php/pkgs/container/php)  for free. Containers default to running Debian, but Alpine images are also available.
 ::
 
-## Understanding containers and Docker
-
-::tip
-New to containers? Check out our [Container Basics guide](/docs/deployment-and-production/container-basics) for a beginner-friendly introduction to Docker and containerization.
+## Quick Start
+::tip{to="/docs/getting-started/container-basics"}
+New to containers? Check out our [Container Basics guide](/docs/getting-started/container-basics) for a beginner-friendly introduction to Docker and containerization.
 ::
 
-If you're new to Docker or containers, you might be wondering why you should containerize your application in the first place. The short answer: **containers let you run your application anywhere** — from your laptop to any cloud provider — with zero changes.
-
-Key benefits of containerization:
-- **Consistency** - Your app runs the same on Mac, Windows, Linux, and production
-- **Confidence** - Infrastructure as code means easier testing and rollbacks
-- **Freedom** - No vendor lock-in; migrate hosts with minimal effort
-- **Simplicity** - Scaling from 1 to 100 containers is straightforward
-
-There are some important terms to understand when working with containers:
-
-| Term | Definition |
-|------|------------|
-| Container | A running instance of an image. |
-| Image | A template for a container to start with (ie. `serversideup/php:8.4-frankenphp`). |
-| Tag | A specific version of an image (ie. `8.4-frankenphp`). |
-| Registry | A repository of images. This is where users can pull images from to start a container. This can be places like [Docker Hub](https://hub.docker.com/r/serversideup/php) or [GitHub Packages](https://github.com/serversideup/docker-php/pkgs/container/php). |
-
-If you'd like to learn more about containers, you can learn more following the guide below.
-
-:u-button{to="/docs/deployment-and-production/container-basics" label="Learn More About Containers" aria-label="Learn More About Containers" size="md" color="primary" variant="outline"  trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}
-
-## Already using Docker?
-If you're already using the official PHP images, switching will literally take you seconds.
-
-:u-button{to="/docs/guide/migrating-from-official-php-images" label="Learn how to migrate from the official PHP images" aria-label="Learn how to migrate from the official PHP images" size="md" color="primary" variant="outline"  trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}
-
-## Quick Start
 In order to run containers, we need a container engine installed such as Docker. You can follow [Docker's installation guide](https://docs.docker.com/get-started/get-docker/) to get started. Confirm Docker is working by running these commands in your terminal:
 ```bash [Terminal]
 # Check Docker version

…ting-started/2.these-images-vs-others.md …ting-started/4.these-images-vs-others.mddocs/content/docs/1.getting-started/2.these-images-vs-others.md renamed to docs/content/docs/1.getting-started/4.these-images-vs-others.md docs/content/docs/1.getting-started/2.these-images-vs-others.md renamed to docs/content/docs/1.getting-started/4.these-images-vs-others.md

@@ -232,19 +232,19 @@ Don't just take our word for it. Here's what developers are experiencing:
 ::
 
 **Time Savings**
-- ⏱️ **Minutes vs Hours** - Go from zero to production-ready PHP in minutes, not hours of server configuration
-- 🔄 **Consistent Deployments** - Eliminate "works on my machine" debugging sessions
-- 📦 **Pre-configured** - Stop researching optimal PHP settings for Laravel
+- **Minutes vs Hours** - Go from zero to production-ready PHP in minutes, not hours of server configuration
+- **Consistent Deployments** - Eliminate "works on my machine" debugging sessions
+- **Pre-configured** - Stop researching optimal PHP settings for Laravel
 
 **Better Security**
-- 🛡️ **Hardened by Default** - Security best practices built-in, not bolted on
-- 🔒 **Regular Updates** - Based on official PHP images with security patches
-- 📋 **Audit Trail** - Infrastructure as code means every change is tracked
+- **Hardened by Default** - Security best practices built-in, not bolted on
+- **Regular Updates** - Based on official PHP images with security patches
+- **Audit Trail** - Infrastructure as code means every change is tracked
 
 **Happier Developers**
-- 😊 **Simple Configuration** - Environment variables instead of config file archaeology
-- 🚀 **Modern Tools** - FrankenPHP, native health checks, and container-native features
-- 🤝 **Community Support** - Active community and comprehensive documentation
+- **Simple Configuration** - Environment variables instead of config file archaeology
+- **Modern Tools** - FrankenPHP, native health checks, and container-native features
+- **Community Support** - Active community and comprehensive documentation
 
 ## Making the Switch
 

…1.getting-started/4.choosing-an-image.md …1.getting-started/5.choosing-an-image.mddocs/content/docs/1.getting-started/4.choosing-an-image.md renamed to docs/content/docs/1.getting-started/5.choosing-an-image.md docs/content/docs/1.getting-started/4.choosing-an-image.md renamed to docs/content/docs/1.getting-started/5.choosing-an-image.md

@@ -122,20 +122,14 @@ In October 2025, NGINX stopped supporting NGINX Unit and archived the project. N
 
 The Unit variation uses NGINX Unit as an application server that runs everything in a single process. Since NGINX Unit is no longer maintained, consider migrating to FrankenPHP for a single-process alternative.
 
-## Operating System
+## Operating Systems
 Choosing an operating system comes down to a few preferences, but ultimately you need to make sure your dependencies are available for the operating system you choose.
 
 | Operating System | Description |
 |-----------|-------------|
 | `debian` (default) | Debian is a popular Linux distribution that is known for its stability and reliability. It is the default operating system for our images. |
 | `alpine` | Alpine is a lightweight Linux distribution that is known for its small size and low resource usage. |
 
-### Debian
-Debian is a popular Linux distribution that is known for its stability and compatibility. It is the default operating system for our images.
-
-### Alpine
-Alpine is a lightweight Linux distribution that is known for its small size and low resource usage. If you're an advanced user, Alpine may be an excellent choice for you.
-
 ### Specific versions
 ::note
 Not all operating systems are available for all image variations and PHP versions. Double check [Docker Hub](https://hub.docker.com/r/serversideup/php/tags){target="_blank"} and [GitHub Packages](https://github.com/serversideup/docker-php/pkgs/container/php){target="_blank"} for the most accurate list of available tags.

…ting-started/5.default-configurations.md …ting-started/6.default-configurations.mddocs/content/docs/1.getting-started/5.default-configurations.md renamed to docs/content/docs/1.getting-started/6.default-configurations.md docs/content/docs/1.getting-started/5.default-configurations.md renamed to docs/content/docs/1.getting-started/6.default-configurations.md

@@ -12,13 +12,21 @@ layout: docs
 All values are defaulted to improve security and performance. We also spent the time to carefully review official documentation and include packages that are required specifically for Laravel and WordPress.
 
 ## Unprivileged by Default
-All images default to running as the OS-native `www-data` user.
 
-::note
-The `www-data` UID/GID is different between Debian (`33:33`) and Alpine (`82:82`). We left these values alone to make these images as native as possible. If you switch between Debian and Alpine, you may need to adjust file permissions in your Docker image and volume mounts.
-::
+All images default to running as the OS-native `www-data` user instead of `root`. This is a critical security practice that limits what an attacker can do if they compromise your container.
+
+### Why this matters
+Running as a non-root user means:
+
+- **Better security**: If someone exploits a vulnerability in your app, they can't gain root access to your container or host system
+- **Production-ready**: This follows Docker and Kubernetes security best practices
+- **Easier compliance**: Many security policies require non-root containers
 
-Since these images are not privileged, that means they are not running on ports less than 1024:
+### What this means for you
+Running unprivileged has two practical implications you should know about:
+
+#### Different ports for web servers
+On Linux systems, only root can bind to ports below 1024 (like 80 and 443). Since our containers don't run as root, they use higher port numbers by default:
 
 | **Variation** | **Default Ports** |
 |---------------|-------------------|
@@ -29,15 +37,35 @@ Since these images are not privileged, that means they are not running on ports
 | unit | HTTP: 8080, HTTPS: 8443 |
 | frankenphp | HTTP: 8080, HTTPS: 8443 |
 
-### How do I run these services on ports 80 and/or 443?
-Almost everyone will want to run these services on ports 80 and 443. If you have an advanced setup, you can use a reverse proxy like Caddy or Traefik to handle the SSL termination and forward the traffic to the container on the non-privileged port.
+#### File permissions to be aware of
+The `www-data` user has different IDs depending on your base operating system:
+- **Debian**: UID/GID `33:33`
+- **Alpine**: UID/GID `82:82`
+
+::tip
+We kept these as the OS defaults to maintain compatibility with other tools and images. If you're mounting volumes from your host machine or switching between Debian and Alpine, you might need to adjust file permissions.
+::
+
+### Running on standard HTTP/HTTPS ports (80 and 443)
+Don't worry—you have two easy options to run your app on the standard web ports:
 
-Or you can simply use Docker's port mapping feature to map the container port to the host port. For example, to run the `fpm-nginx` variation on port 80 and 443, you can run the following command:
+#### Docker port mapping (recommended for development)
+Use Docker's built-in port mapping to route traffic from port 80/443 on your host to the container's higher ports:
 
 ```bash [Terminal]
 docker run -p 80:8080 -p 443:8443 serversideup/php:8.4-fpm-nginx
 ```
 
+This tells Docker: "Take traffic coming to port 80 on my machine and send it to port 8080 in the container."
+
+#### Reverse proxy (recommended for production)
+Use a reverse proxy like [Caddy](https://caddyserver.com/){target="_blank"}, [Traefik](https://traefik.io/){target="_blank"}, or [NGINX](https://nginx.org/){target="_blank"} to handle SSL certificates and route traffic to your containers. This is the preferred approach for production because it:
+- Automatically handles SSL certificate generation and renewal
+- Can route to multiple containers/services
+- Provides additional security features like rate limiting
+
+:u-button{to="/docs/deployment-and-production/configuring-ssl" label="Learn about SSL configuration" aria-label="Learn about SSL configuration" size="md" color="primary" variant="outline"  trailing-icon="i-lucide-arrow-right" class="font-bold ring ring-inset ring-blue-600 text-blue-600 hover:ring-blue-500 hover:text-blue-500"}
+
 ## Default Environment Variables
 Environment variables give you a ton of flexibility to customize your container without the complexity of mounting custom configuration files. By default, these images are set to production-ready values. You can read more about the available environment variables below.