Restructured content to flow better in docs

Author: jaydrogers

…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.
 
@@ -179,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

@@ -1,14 +1,64 @@
 ---
-head.title: 'Migration Guide - Server Side Up'
-description: 'Learn how to migrate from serversideup/php images to the latest version.'
+head.title: 'Upgrade Guide - Docker PHP - Server Side Up'
+description: 'Learn how the serversideup/php Docker images are built and how to upgrade.'
 layout: docs
-title: Migration Guide
+title: Upgrade Guide
 ---
-::lead-p
-This guide is created to help you migrate from your current serversideup/php images to the latest version.
-::
 
-## Version 3 → Version 4
+## Subscribe to repository updates
+Regardless if you are choosing to use automatic updates or manual updates, it is highly advised to subscribe to our releases. You can do this through the "Watch" button on our [GitHub](https://github.com/serversideup/docker-php).
+
+![Watch Repository](images/docs/watch-repo.png){.max-w-md.w-full.h-auto.mx-auto}
+
+:u-button{to="https://github.com/serversideup/docker-php" target="_blank" label="Subscribe to our Repo" aria-label="Subscribe to our Repo" 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"}
+
+## Choosing an image version
+
+If you do not select a specific patch version, then you will receive automatic PHP updates.
+
+For example, you can select your version based on the different version numbers:
+- Major Version (example: `8` will give you the latest 8.x version)
+- Minor Version (example: `8.4` will give you the latest 8.4.x version)
+- Patch Version (example: `8.4.1` will always stay at the 8.4.1 version)
+
+If you use `latest`, you will always get the latest stable version of the CLI variation of PHP. For the best stability in production environments, you may want to pin to a specific patch version (example: `8.4.1`).
+
+If you need help choosing an image, see our guide below.
+
+:u-button{to="/docs/getting-started/choosing-an-image" label="Learn more about choosing an image" aria-label="Learn more about choosing an image" 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"}
+
+## Release process
+All source code is merged into the `main` branch, which automatically build our "beta" images.
+
+After testing the images internally and from other community members, we will [publish a release on GitHub](https://github.com/serversideup/docker-php/releases) with a detailed changelog.
+
+## Updating the Docker images on your own
+If you You and simply run `apt-get update && apt-get upgrade` within your own image, but still want the image to receive other operating system updates, you will need to run the following commands on your build.
+
+Any updates that you apply have a risk of breaking other things inside the container. Be sure to have a good testing process in place before applying updates to your production environment.
+
+#### Example Dockerfile with manual updates for Debian
+```dockerfile [Dockerfile]
+FROM serversideup/php:8.4.1-fpm-nginx
+
+RUN apt-get update \
+    && apt-get upgrade -y \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*
+```
+
+If you're running an Alpine-based image, you can use the following commands:
+
+#### Example Dockerfile with manual updates for Alpine
+```dockerfile [Dockerfile]
+FROM serversideup/php:8.4.1-fpm-nginx-alpine
+
+RUN apk update \
+    && apk upgrade \
+    && rm -rf /var/cache/apk/*
+```
+
+## Version 3 → Version 4 Migration
 Version 3 to Version 4 is a much easier migration compared to previous versions. There are **no breaking changes**, so you can simply update your image tag to the latest version and take advantage of the new features.
 
 ### New Features in Version 4
@@ -67,7 +117,7 @@ services:
 
 That's it! Version 4 is designed to be a smooth, non-breaking upgrade that gives you more flexibility and features when you need them.
 
-## Version 2 → Version 3
+## Version 2 → Version 3 Migration
 If you're an existing user of our v2 images, be sure that your current configurations are NOT set to use the latest images. To do this, you can lock your images into the `v2.2.1` tag. This will ensure that you're not automatically upgraded to the v3 images.
 
 For example, if you are using `8.2-fpm-nginx`, you would change your `compose.yml` file to use the [`v2.2.1`](https://hub.docker.com/r/serversideup/php/tags?page=1&name=2.2.1){target="_blank"} tag:
@@ -223,3 +273,4 @@ USER www-data
 #### Deployment
 - CI/CD with valid tests is always encouraged
 - After completing all steps above, you're now ready to deploy the new images
+