From 5b27e893915e7cddf3e04187334a997df5716207 Mon Sep 17 00:00:00 2001
From: Jay Rogers <3174134+jaydrogers@users.noreply.github.com>
Date: Tue, 27 Jan 2026 09:59:12 -0600
Subject: [PATCH 1/5] Add TRUSTED_PROXY support for all variations & Caddy
 global imports (#643)

* Enhance trusted proxy support across configurations

Updated documentation and configuration files to improve trusted proxy handling. Introduced customizable trusted proxy settings for Cloudflare, Sucuri, and local proxies, ensuring accurate IP logging. Removed hardcoded Cloudflare IPs from NGINX and Apache configurations, replacing them with a dynamic inclusion based on the TRUSTED_PROXY environment variable.

* Clarify trusted proxy documentation for Cloudflare and Sucuri

Updated the documentation to specify that both Cloudflare and Sucuri configurations now automatically include local Docker networks. Added a tip to inform users that they can use the `cloudflare` setting while also trusting local proxies, enhancing clarity on trusted proxy usage.

* Add global Caddy configuration support in FrankenPHP

Updated the Dockerfile to create a directory for global Caddy configurations and modified the Caddyfile to import additional configuration files from the new caddyfile-global.d directory, enhancing flexibility in Caddy setup.

* Fix Dockerfile syntax by correcting line continuation for Caddy configuration paths
---
 .../4.these-images-vs-others.md               |   2 +-
 .../5.guide/4.configuring-trusted-proxies.md  | 350 ++++++++++++++++++
 .../1.environment-variable-specification.md   |   1 +
 docs/content/index.md                         |   4 +-
 .../entrypoint.d/10-init-webserver-config.sh  |   4 +-
 src/variations/fpm-apache/Dockerfile          |   3 +-
 .../etc/apache2/conf-available/remoteip.conf  |  31 +-
 .../etc/apache2/sites-available/ssl-full.conf |   3 -
 .../etc/apache2/trusted-proxy/cloudflare.conf |  37 ++
 .../etc/apache2/trusted-proxy/local.conf      |  14 +
 .../etc/apache2/trusted-proxy/off.conf        |   1 +
 .../etc/apache2/trusted-proxy/sucuri.conf     |  21 ++
 .../etc/apache2/vhost-templates/http.conf     |   3 -
 .../etc/apache2/vhost-templates/https.conf    |   3 -
 src/variations/fpm-nginx/Dockerfile           |   3 +-
 .../etc/nginx/site-opts.d/http.conf.template  |   3 +
 .../etc/nginx/site-opts.d/https.conf.template |   3 +
 .../cloudflare.conf}                          |  10 +-
 .../etc/nginx/trusted-proxy/local.conf        |  14 +
 .../etc/nginx/trusted-proxy/off.conf          |   1 +
 .../etc/nginx/trusted-proxy/sucuri.conf       |  22 ++
 src/variations/frankenphp/Dockerfile          |   4 +-
 .../frankenphp/etc/frankenphp/Caddyfile       |  40 +-
 .../trusted-proxy/cloudflare.caddyfile        |  36 ++
 .../frankenphp/trusted-proxy/local.caddyfile  |  12 +
 .../frankenphp/trusted-proxy/off.caddyfile    |   1 +
 .../frankenphp/trusted-proxy/sucuri.caddyfile |  18 +
 27 files changed, 562 insertions(+), 82 deletions(-)
 create mode 100644 docs/content/docs/5.guide/4.configuring-trusted-proxies.md
 create mode 100644 src/variations/fpm-apache/etc/apache2/trusted-proxy/cloudflare.conf
 create mode 100644 src/variations/fpm-apache/etc/apache2/trusted-proxy/local.conf
 create mode 100644 src/variations/fpm-apache/etc/apache2/trusted-proxy/off.conf
 create mode 100644 src/variations/fpm-apache/etc/apache2/trusted-proxy/sucuri.conf
 rename src/variations/fpm-nginx/etc/nginx/{server-opts.d/remoteip.conf => trusted-proxy/cloudflare.conf} (79%)
 create mode 100644 src/variations/fpm-nginx/etc/nginx/trusted-proxy/local.conf
 create mode 100644 src/variations/fpm-nginx/etc/nginx/trusted-proxy/off.conf
 create mode 100644 src/variations/fpm-nginx/etc/nginx/trusted-proxy/sucuri.conf
 create mode 100644 src/variations/frankenphp/etc/frankenphp/trusted-proxy/cloudflare.caddyfile
 create mode 100644 src/variations/frankenphp/etc/frankenphp/trusted-proxy/local.caddyfile
 create mode 100644 src/variations/frankenphp/etc/frankenphp/trusted-proxy/off.caddyfile
 create mode 100644 src/variations/frankenphp/etc/frankenphp/trusted-proxy/sucuri.caddyfile

diff --git a/docs/content/docs/1.getting-started/4.these-images-vs-others.md b/docs/content/docs/1.getting-started/4.these-images-vs-others.md
index 0d6f7941b..f0c70f0ce 100644
--- a/docs/content/docs/1.getting-started/4.these-images-vs-others.md
+++ b/docs/content/docs/1.getting-started/4.these-images-vs-others.md
@@ -72,7 +72,7 @@ Our images run as the `www-data` user by default, following the principle of lea
 We also include additional security hardening:
 - Disabled dangerous PHP functions by default (but you control them)
 - Proper file permissions out of the box
-- CloudFlare trusted proxy support for accurate IP logging
+- Customizable trusted proxy configuration (Cloudflare, Sucuri, local, or off) for accurate IP logging
 - Regular security updates from official PHP base images
 
 ### Performance Optimized
diff --git a/docs/content/docs/5.guide/4.configuring-trusted-proxies.md b/docs/content/docs/5.guide/4.configuring-trusted-proxies.md
new file mode 100644
index 000000000..e076b321c
--- /dev/null
+++ b/docs/content/docs/5.guide/4.configuring-trusted-proxies.md
@@ -0,0 +1,350 @@
+---
+head.title: 'Configuring Trusted Proxies - Docker PHP - Server Side Up'
+description: 'Learn how to configure trusted proxies to get accurate client IP addresses when running behind load balancers, CDNs, or reverse proxies.'
+layout: docs
+---
+
+::lead-p
+When your application runs behind a load balancer, CDN, or reverse proxy, the web server sees the proxy's IP address instead of the actual visitor's IP. Trusted proxy configuration tells your web server which proxies to trust for forwarding the real client IP.
+::
+
+## Why Trusted Proxies Matter
+
+Without proper trusted proxy configuration, your application will:
+- Log the proxy's IP address instead of the visitor's real IP
+- Have incorrect geolocation data
+- Potentially break rate limiting or IP-based security rules
+- Show incorrect information in Laravel's `request()->ip()` or similar methods
+
+::warning
+Never trust all IP addresses as proxies. Only trust specific proxy IPs that you control or know are legitimate (like your CDN provider).
+::
+
+## Available Options
+
+Set the `TRUSTED_PROXY` environment variable to one of the following values:
+
+| Value | Description |
+|-------|-------------|
+| `cloudflare` (default) | Trusts [Cloudflare's IP ranges](https://www.cloudflare.com/ips/){target="_blank"} **+ local Docker networks** using the `CF-Connecting-IP` header |
+| `sucuri` | Trusts [Sucuri's IP ranges](https://docs.sucuri.net/website-firewall/sucuri-firewall-troubleshooting-guide/){target="_blank"} **+ local Docker networks** using the `X-Forwarded-For` header |
+| `local` | Trusts only private/local network ranges (Docker networks, localhost) using the `X-Forwarded-For` header |
+| `off` | Disables trusted proxy configuration entirely |
+
+::tip
+**You don't need to choose between your CDN and local proxies.** All options (except `off`) automatically include Docker's internal network ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`). This means if you're behind Cloudflare *and* running a reverse proxy like Traefik or Caddy in Docker, just use `cloudflare` — it already trusts both.
+::
+
+## Quick Start
+
+### Using Cloudflare (Default)
+
+If you're using Cloudflare as your CDN/proxy, you don't need to change anything. The default configuration already trusts Cloudflare's IP ranges:
+
+```yml [compose.yml]
+services:
+  php:
+    image: serversideup/php:8.5-fpm-nginx
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    # TRUSTED_PROXY defaults to "cloudflare"
+```
+
+### Using Sucuri
+
+If you're using Sucuri as your web application firewall:
+
+```yml [compose.yml]{8}
+services:
+  php:
+    image: serversideup/php:8.5-fpm-nginx
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    environment:
+      TRUSTED_PROXY: "sucuri"
+```
+
+### Local/Docker Networks Only
+
+If you're running behind your own reverse proxy (like Traefik or Caddy) on the same Docker network:
+
+```yml [compose.yml]{8}
+services:
+  php:
+    image: serversideup/php:8.5-fpm-nginx
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    environment:
+      TRUSTED_PROXY: "local"
+```
+
+### Disabling Trusted Proxies
+
+If you want to handle proxy configuration yourself or your application is directly exposed to the internet:
+
+```yml [compose.yml]{8}
+services:
+  php:
+    image: serversideup/php:8.5-fpm-nginx
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    environment:
+      TRUSTED_PROXY: "off"
+```
+
+## Laravel Configuration
+
+While the Docker images handle the web server's trusted proxy configuration, Laravel also needs to know about trusted proxies at the application level. 
+
+Laravel includes a `TrustProxies` middleware that you should configure in your application. For most setups using our images, you can trust all proxies since the web server has already validated them:
+
+```php [bootstrap/app.php]
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->trustProxies(at: '*');
+})
+```
+
+Or if you prefer more control, configure specific headers:
+
+```php [bootstrap/app.php]
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->trustProxies(
+        at: '*',
+        headers: Request::HEADER_X_FORWARDED_FOR |
+                 Request::HEADER_X_FORWARDED_HOST |
+                 Request::HEADER_X_FORWARDED_PORT |
+                 Request::HEADER_X_FORWARDED_PROTO
+    );
+})
+```
+
+::tip
+For Cloudflare specifically, Laravel can use the `CF-Connecting-IP` header. The `HEADER_X_FORWARDED_FOR` setting works because Cloudflare also sets this header.
+::
+
+:u-button{to="https://laravel.com/docs/requests#trusting-proxies" target="_blank" label="Learn more about Laravel's TrustProxies middleware" aria-label="Learn more about Laravel's TrustProxies middleware" 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"}
+
+## How It Works
+
+### Cloudflare
+When `TRUSTED_PROXY=cloudflare`:
+- Trusts Cloudflare's published IPv4 and IPv6 ranges
+- Uses the `CF-Connecting-IP` header to get the real client IP
+- Includes Docker network ranges for container-to-container communication
+
+### Sucuri
+When `TRUSTED_PROXY=sucuri`:
+- Trusts Sucuri's WAF IP ranges
+- Uses the `X-Forwarded-For` header to get the real client IP
+- Includes Docker network ranges for container-to-container communication
+
+### Local
+When `TRUSTED_PROXY=local`:
+- Trusts only private network ranges (RFC 1918)
+- Trusts localhost and IPv6 loopback addresses
+- Uses the `X-Forwarded-For` header
+- Perfect for setups with your own reverse proxy on the same network
+
+## Security Considerations
+
+::caution
+Incorrectly configuring trusted proxies can allow attackers to spoof their IP address by sending fake headers. Only trust IP ranges that you know are legitimate proxies.
+::
+
+- **Don't trust all IPs**: Never set your web server to trust `X-Forwarded-For` from any IP address
+- **Keep configurations updated**: CDN IP ranges can change over time. Our images are updated regularly, but if security is critical, verify the ranges match your provider's published list
+- **Use the right option**: If you're not using Cloudflare or Sucuri, don't use those options. Use `local` if you have your own reverse proxy, or `off` if you don't need proxy trust
+
+## Troubleshooting
+
+### Still seeing proxy IP instead of real IP
+
+1. **Check your CDN/proxy is in the trusted list**: Verify your proxy's IP is within the trusted ranges for your chosen option
+2. **Check the header being used**: Different proxies use different headers. Cloudflare uses `CF-Connecting-IP`, while most others use `X-Forwarded-For`
+3. **Check Laravel configuration**: Remember to also configure Laravel's `TrustProxies` middleware
+
+### Application works but logs show wrong IP
+
+Your web server might be configured correctly, but your application framework might need separate configuration. See the [Laravel Configuration](#laravel-configuration) section above.
+
+### Need to trust a different proxy provider
+
+If your proxy provider isn't listed, you can create a custom configuration. See [Custom Trusted Proxy Configuration](#custom-trusted-proxy-configuration) below.
+
+## Custom Trusted Proxy Configuration
+
+If you're using a proxy provider that isn't included (like AWS ALB, Fastly, or a custom load balancer), you can create your own trusted proxy configuration.
+
+### Two Ways to Add Custom Configs
+
+| Method | Best For | How It Works |
+|--------|----------|--------------|
+| **Dockerfile (recommended)** | Production deployments | Bakes the config into your image |
+| **Volume mount** | Local development | Mount the file at runtime |
+
+The examples below use the Dockerfile approach. To use a volume mount instead, simply replace the `COPY` instruction with a volume mount in your `compose.yml`:
+
+```yml [compose.yml]
+volumes:
+  # Mount syntax: ./local/path:/container/path:ro
+  - ./docker/trusted-proxy/aws-alb.conf:/etc/nginx/trusted-proxy/aws-alb.conf:ro
+```
+
+| Variation | Config Path |
+|-----------|-------------|
+| `fpm-nginx` | `/etc/nginx/trusted-proxy/{name}.conf` |
+| `fpm-apache` | `/etc/apache2/trusted-proxy/{name}.conf` |
+| `frankenphp` | `/etc/frankenphp/trusted-proxy/{name}.caddyfile` |
+
+::tip
+Always include Docker's internal network ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) so container-to-container communication works correctly.
+::
+
+::warning
+Keep your custom IP ranges up to date. Cloud providers periodically update their IP ranges.
+::
+
+### FPM-NGINX Custom Configuration
+
+::code-tree{defaultValue="Dockerfile"}
+
+```dockerfile [Dockerfile]
+FROM serversideup/php:8.5-fpm-nginx
+
+# Copy our custom trusted proxy configuration
+COPY --chmod=644 docker/trusted-proxy/aws-alb.conf /etc/nginx/trusted-proxy/aws-alb.conf
+```
+
+```yml [compose.yml]
+services:
+  php:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    environment:
+      TRUSTED_PROXY: "aws-alb"
+```
+
+```conf [docker/trusted-proxy/aws-alb.conf]
+##
+# AWS ALB - Trusted Proxy (example)
+##
+
+# Configure docker networks and loopback addresses
+set_real_ip_from 10.0.0.0/8;
+set_real_ip_from 172.16.0.0/12;
+set_real_ip_from 192.168.0.0/16;
+set_real_ip_from 127.0.0.1/8;
+set_real_ip_from ::1;
+set_real_ip_from fd00::/8;
+
+# Add your proxy provider's IP ranges
+# Example: AWS us-east-1 ranges (check AWS docs for current IPs)
+set_real_ip_from 3.0.0.0/8;
+
+# Set the header your proxy uses
+real_ip_header X-Forwarded-For;
+```
+::
+
+### FPM-Apache Custom Configuration
+
+::code-tree{defaultValue="Dockerfile"}
+
+```dockerfile [Dockerfile]
+FROM serversideup/php:8.5-fpm-apache
+
+# Copy our custom trusted proxy configuration
+COPY --chmod=644 docker/trusted-proxy/aws-alb.conf /etc/apache2/trusted-proxy/aws-alb.conf
+```
+
+```yml [compose.yml]
+services:
+  php:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    environment:
+      TRUSTED_PROXY: "aws-alb"
+```
+
+```conf [docker/trusted-proxy/aws-alb.conf]
+##
+# AWS ALB - Trusted Proxy (example)
+##
+
+# Set the header your proxy uses
+RemoteIPHeader X-Forwarded-For
+
+# Configure docker networks
+RemoteIPTrustedProxy 10.0.0.0/8
+RemoteIPTrustedProxy 172.16.0.0/12
+RemoteIPTrustedProxy 192.168.0.0/16
+RemoteIPTrustedProxy 127.0.0.1/8
+RemoteIPTrustedProxy ::1
+RemoteIPTrustedProxy fd00::/8
+
+# Add your proxy provider's IP ranges
+# Example: AWS us-east-1 ranges (check AWS docs for current IPs)
+RemoteIPTrustedProxy 3.0.0.0/8
+```
+::
+
+### FrankenPHP Custom Configuration
+
+::code-tree{defaultValue="Dockerfile"}
+
+```dockerfile [Dockerfile]
+FROM serversideup/php:8.5-frankenphp
+
+# Copy our custom trusted proxy configuration
+COPY --chmod=644 docker/trusted-proxy/aws-alb.caddyfile /etc/frankenphp/trusted-proxy/aws-alb.caddyfile
+```
+
+```yml [compose.yml]
+services:
+  php:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "80:8080"
+    volumes:
+      - .:/var/www/html
+    environment:
+      TRUSTED_PROXY: "aws-alb"
+```
+
+```caddyfile [docker/trusted-proxy/aws-alb.caddyfile]
+servers {
+	# Trust Docker/private networks + loopback
+	trusted_proxies static \
+10.0.0.0/8 \
+172.16.0.0/12 \
+192.168.0.0/16 \
+127.0.0.1/8 \
+::1 \
+fd00::/8 \
+3.0.0.0/8
+
+	# Set the header your proxy uses
+	client_ip_headers X-Forwarded-For
+}
+```
+::
diff --git a/docs/content/docs/8.reference/1.environment-variable-specification.md b/docs/content/docs/8.reference/1.environment-variable-specification.md
index 0b6d28f4d..e839b3ec7 100644
--- a/docs/content/docs/8.reference/1.environment-variable-specification.md
+++ b/docs/content/docs/8.reference/1.environment-variable-specification.md
@@ -119,3 +119,4 @@ Setting environment variables all depends on what method you're using to run you
 `SSL_CERTIFICATE_FILE`<br />*Default: "/etc/ssl/private/self-signed-web.crt"*|Path to public certificate file for HTTPS. You must provide this file otherwise a self-signed key pair will be generated for you.|fpm-nginx,<br />fpm-apache
 `SSL_MODE`<br />*Default: "off"*|Configure how you would like to handle SSL. This can be "off" (HTTP only), "mixed" (HTTP + HTTPS), or "full" (HTTPS only). If you use HTTP, you may need to also change `PHP_SESSION_COOKIE_SECURE`.|fpm-nginx,<br />fpm-apache,<br />frankenphp
 `SSL_PRIVATE_KEY_FILE`<br />*Default: "/etc/ssl/private/self-signed-web.key"*|Path to private key file for HTTPS. You must provide this file otherwise a self-signed key pair will be generated for you.|fpm-nginx,<br />fpm-apache, <br />frankenphp
+`TRUSTED_PROXY`<br />*Default: "cloudflare"*|Configure which proxy IPs are trusted to pass the real client IP address. Valid options: `cloudflare`, `sucuri`, `local`, or `off`. See [Configuring Trusted Proxies](/docs/guide/configuring-trusted-proxies) for details.|fpm-nginx,<br />fpm-apache, <br />frankenphp
diff --git a/docs/content/index.md b/docs/content/index.md
index a6cbf94d9..a9e76dda7 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -105,10 +105,10 @@ These images [give a lot more]{.text-pink-500} than other PHP Docker Images.
     orientation: vertical
     ---
     #title
-    Native CloudFlare Support
+    Trusted Proxy Support
 
     #description
-    Get real IP addresses from visitors from trusted proxies.
+    Get real IP addresses from Cloudflare, Sucuri, or local proxies.
     :::
 
     :::u-page-card
diff --git a/src/s6/etc/entrypoint.d/10-init-webserver-config.sh b/src/s6/etc/entrypoint.d/10-init-webserver-config.sh
index a34608d75..4a06a093b 100644
--- a/src/s6/etc/entrypoint.d/10-init-webserver-config.sh
+++ b/src/s6/etc/entrypoint.d/10-init-webserver-config.sh
@@ -42,8 +42,8 @@ process_template() {
         return 1
     fi
 
-    # Get all environment variables starting with 'NGINX_', 'SSL_', `LOG_`, 'APACHE_', and 'HEALTHCHECK_PATH'
-    subst_vars=$(env | grep -E '^(PHP_|NGINX_|SSL_|LOG_|APACHE_|HEALTHCHECK_PATH)' | cut -d= -f1 | awk '{printf "${%s},",$1}' | sed 's/,$//')
+    # Get all environment variables starting with certain prefixes
+    subst_vars=$(env | grep -E '^(PHP_|NGINX_|SSL_|LOG_|APACHE_|HEALTHCHECK_PATH|TRUSTED_PROXY)' | cut -d= -f1 | awk '{printf "${%s},",$1}' | sed 's/,$//')
 
     # Validate that all required variables are set
     for var_name in $(echo "$subst_vars" | tr ',' ' '); do
diff --git a/src/variations/fpm-apache/Dockerfile b/src/variations/fpm-apache/Dockerfile
index 3d4e52f55..0fa0d3fc1 100644
--- a/src/variations/fpm-apache/Dockerfile
+++ b/src/variations/fpm-apache/Dockerfile
@@ -99,7 +99,8 @@ ENV APACHE_DOCUMENT_ROOT=/var/www/html/public \
     SHOW_WELCOME_MESSAGE=true \
     SSL_MODE=off \
     SSL_CERTIFICATE_FILE=/etc/ssl/private/self-signed-web.crt \
-    SSL_PRIVATE_KEY_FILE=/etc/ssl/private/self-signed-web.key
+    SSL_PRIVATE_KEY_FILE=/etc/ssl/private/self-signed-web.key \
+    TRUSTED_PROXY=cloudflare
 
 # copy our scripts
 COPY --chmod=755 src/common/ /
diff --git a/src/variations/fpm-apache/etc/apache2/conf-available/remoteip.conf b/src/variations/fpm-apache/etc/apache2/conf-available/remoteip.conf
index 59724b0aa..b6e3a544e 100644
--- a/src/variations/fpm-apache/etc/apache2/conf-available/remoteip.conf
+++ b/src/variations/fpm-apache/etc/apache2/conf-available/remoteip.conf
@@ -1,26 +1,5 @@
-RemoteIPHeader CF-Connecting-IP
-RemoteIPTrustedProxy 173.245.48.0/20
-RemoteIPTrustedProxy 103.21.244.0/22
-RemoteIPTrustedProxy 103.22.200.0/22
-RemoteIPTrustedProxy 103.31.4.0/22
-RemoteIPTrustedProxy 141.101.64.0/18
-RemoteIPTrustedProxy 108.162.192.0/18
-RemoteIPTrustedProxy 190.93.240.0/20
-RemoteIPTrustedProxy 188.114.96.0/20
-RemoteIPTrustedProxy 197.234.240.0/22
-RemoteIPTrustedProxy 198.41.128.0/17
-RemoteIPTrustedProxy 162.158.0.0/15
-RemoteIPTrustedProxy 172.64.0.0/13
-RemoteIPTrustedProxy 131.0.72.0/22
-RemoteIPTrustedProxy 104.16.0.0/13
-RemoteIPTrustedProxy 104.24.0.0/14
-RemoteIPTrustedProxy 2400:cb00::/32
-RemoteIPTrustedProxy 2606:4700::/32
-RemoteIPTrustedProxy 2803:f800::/32
-RemoteIPTrustedProxy 2405:b500::/32
-RemoteIPTrustedProxy 2405:8100::/32
-RemoteIPTrustedProxy 2a06:98c0::/29
-RemoteIPTrustedProxy 2c0f:f248::/32
-RemoteIPTrustedProxy 10.0.0.0/8
-RemoteIPTrustedProxy 172.16.0.0/12
-RemoteIPTrustedProxy 192.168.0.0/16
\ No newline at end of file
+#
+# Trusted Proxy Configuration
+# Available options: cloudflare, sucuri, local, off
+#
+Include /etc/apache2/trusted-proxy/${TRUSTED_PROXY}.conf
\ No newline at end of file
diff --git a/src/variations/fpm-apache/etc/apache2/sites-available/ssl-full.conf b/src/variations/fpm-apache/etc/apache2/sites-available/ssl-full.conf
index 056ddde91..c6b8406ac 100644
--- a/src/variations/fpm-apache/etc/apache2/sites-available/ssl-full.conf
+++ b/src/variations/fpm-apache/etc/apache2/sites-available/ssl-full.conf
@@ -3,9 +3,6 @@
     ServerName localhost
     ServerAdmin webmaster@localhost
 
-    # Set CloudFlare Real IP
-    RemoteIPHeader CF-Connecting-IP
-
     # Turn on rewrite engine
     RewriteEngine On
     
diff --git a/src/variations/fpm-apache/etc/apache2/trusted-proxy/cloudflare.conf b/src/variations/fpm-apache/etc/apache2/trusted-proxy/cloudflare.conf
new file mode 100644
index 000000000..9d58bc45b
--- /dev/null
+++ b/src/variations/fpm-apache/etc/apache2/trusted-proxy/cloudflare.conf
@@ -0,0 +1,37 @@
+##
+## Cloudflare - Trusted Proxy
+##
+
+# Set RealIP header
+RemoteIPHeader CF-Connecting-IP
+
+# Allow Cloudflare's IP addresses
+# IP source: https://www.cloudflare.com/ips/
+
+RemoteIPTrustedProxy 173.245.48.0/20
+RemoteIPTrustedProxy 103.21.244.0/22
+RemoteIPTrustedProxy 103.22.200.0/22
+RemoteIPTrustedProxy 103.31.4.0/22
+RemoteIPTrustedProxy 141.101.64.0/18
+RemoteIPTrustedProxy 108.162.192.0/18
+RemoteIPTrustedProxy 190.93.240.0/20
+RemoteIPTrustedProxy 188.114.96.0/20
+RemoteIPTrustedProxy 197.234.240.0/22
+RemoteIPTrustedProxy 198.41.128.0/17
+RemoteIPTrustedProxy 162.158.0.0/15
+RemoteIPTrustedProxy 172.64.0.0/13
+RemoteIPTrustedProxy 131.0.72.0/22
+RemoteIPTrustedProxy 104.16.0.0/13
+RemoteIPTrustedProxy 104.24.0.0/14
+RemoteIPTrustedProxy 2400:cb00::/32
+RemoteIPTrustedProxy 2606:4700::/32
+RemoteIPTrustedProxy 2803:f800::/32
+RemoteIPTrustedProxy 2405:b500::/32
+RemoteIPTrustedProxy 2405:8100::/32
+RemoteIPTrustedProxy 2a06:98c0::/29
+RemoteIPTrustedProxy 2c0f:f248::/32
+
+# Configure docker networks
+RemoteIPTrustedProxy 10.0.0.0/8
+RemoteIPTrustedProxy 172.16.0.0/12
+RemoteIPTrustedProxy 192.168.0.0/16
\ No newline at end of file
diff --git a/src/variations/fpm-apache/etc/apache2/trusted-proxy/local.conf b/src/variations/fpm-apache/etc/apache2/trusted-proxy/local.conf
new file mode 100644
index 000000000..417f20553
--- /dev/null
+++ b/src/variations/fpm-apache/etc/apache2/trusted-proxy/local.conf
@@ -0,0 +1,14 @@
+##
+## Local - Trusted Proxy
+##
+
+# Set RealIP header
+RemoteIPHeader X-Forwarded-For
+
+# Configure docker networks
+RemoteIPTrustedProxy 10.0.0.0/8
+RemoteIPTrustedProxy 172.16.0.0/12
+RemoteIPTrustedProxy 192.168.0.0/16
+RemoteIPTrustedProxy 127.0.0.1/8
+RemoteIPTrustedProxy ::1
+RemoteIPTrustedProxy fd00::/8
\ No newline at end of file
diff --git a/src/variations/fpm-apache/etc/apache2/trusted-proxy/off.conf b/src/variations/fpm-apache/etc/apache2/trusted-proxy/off.conf
new file mode 100644
index 000000000..8dc31e72c
--- /dev/null
+++ b/src/variations/fpm-apache/etc/apache2/trusted-proxy/off.conf
@@ -0,0 +1 @@
+# Include nothing when TRUSTED_PROXY is set to off
\ No newline at end of file
diff --git a/src/variations/fpm-apache/etc/apache2/trusted-proxy/sucuri.conf b/src/variations/fpm-apache/etc/apache2/trusted-proxy/sucuri.conf
new file mode 100644
index 000000000..24917082a
--- /dev/null
+++ b/src/variations/fpm-apache/etc/apache2/trusted-proxy/sucuri.conf
@@ -0,0 +1,21 @@
+##
+## Sucuri - Trusted Proxy
+##
+
+# Set RealIP header
+RemoteIPHeader X-Forwarded-For
+
+# Allow Sucuri's IP addresses
+# IP source: https://docs.sucuri.net/website-firewall/sucuri-firewall-troubleshooting-guide/
+
+# Configure docker networks
+RemoteIPTrustedProxy 10.0.0.0/8
+RemoteIPTrustedProxy 172.16.0.0/12
+RemoteIPTrustedProxy 192.168.0.0/16
+
+# Allow Sucuri's IP addresses
+RemoteIPTrustedProxy 192.88.134.0/23
+RemoteIPTrustedProxy 185.93.228.0/22
+RemoteIPTrustedProxy 66.248.200.0/22
+RemoteIPTrustedProxy 2a02:fe80::/29
+RemoteIPTrustedProxy 208.109.0.0/22
\ No newline at end of file
diff --git a/src/variations/fpm-apache/etc/apache2/vhost-templates/http.conf b/src/variations/fpm-apache/etc/apache2/vhost-templates/http.conf
index 5684f34da..8284272f7 100644
--- a/src/variations/fpm-apache/etc/apache2/vhost-templates/http.conf
+++ b/src/variations/fpm-apache/etc/apache2/vhost-templates/http.conf
@@ -2,9 +2,6 @@
 ServerName localhost
 ServerAdmin webmaster@localhost
 
-# Set CloudFlare Real IP
-RemoteIPHeader CF-Connecting-IP
-
 # Configure main document root
 DocumentRoot ${APACHE_DOCUMENT_ROOT}
 
diff --git a/src/variations/fpm-apache/etc/apache2/vhost-templates/https.conf b/src/variations/fpm-apache/etc/apache2/vhost-templates/https.conf
index f2831f45f..c721ece56 100644
--- a/src/variations/fpm-apache/etc/apache2/vhost-templates/https.conf
+++ b/src/variations/fpm-apache/etc/apache2/vhost-templates/https.conf
@@ -7,9 +7,6 @@ Protocols h2 http/1.1
 
 SSLProtocol -all +TLSv1.2 +TLSv1.3
 
-# Set CloudFlare Real IP
-RemoteIPHeader CF-Connecting-IP
-
 # Configure main document root
 DocumentRoot ${APACHE_DOCUMENT_ROOT}
 
diff --git a/src/variations/fpm-nginx/Dockerfile b/src/variations/fpm-nginx/Dockerfile
index 83518d33d..e945a3d57 100644
--- a/src/variations/fpm-nginx/Dockerfile
+++ b/src/variations/fpm-nginx/Dockerfile
@@ -173,7 +173,8 @@ ENV APP_BASE_DIR=/var/www/html \
     SHOW_WELCOME_MESSAGE=true \
     SSL_MODE=off \
     SSL_CERTIFICATE_FILE=/etc/ssl/private/self-signed-web.crt \
-    SSL_PRIVATE_KEY_FILE=/etc/ssl/private/self-signed-web.key
+    SSL_PRIVATE_KEY_FILE=/etc/ssl/private/self-signed-web.key \
+    TRUSTED_PROXY=cloudflare
 
 # copy our scripts
 COPY --chmod=755 src/common/ /
diff --git a/src/variations/fpm-nginx/etc/nginx/site-opts.d/http.conf.template b/src/variations/fpm-nginx/etc/nginx/site-opts.d/http.conf.template
index 08a90ff96..3b2cd4b7b 100644
--- a/src/variations/fpm-nginx/etc/nginx/site-opts.d/http.conf.template
+++ b/src/variations/fpm-nginx/etc/nginx/site-opts.d/http.conf.template
@@ -47,5 +47,8 @@ location ~ \.php$ {
     fastcgi_read_timeout $PHP_MAX_EXECUTION_TIME;
 }
 
+# trusted proxy configuration
+include /etc/nginx/trusted-proxy/${TRUSTED_PROXY}.conf;
+
 # additional config
 include /etc/nginx/server-opts.d/*.conf;
\ No newline at end of file
diff --git a/src/variations/fpm-nginx/etc/nginx/site-opts.d/https.conf.template b/src/variations/fpm-nginx/etc/nginx/site-opts.d/https.conf.template
index 810ff0747..a796f5d7f 100644
--- a/src/variations/fpm-nginx/etc/nginx/site-opts.d/https.conf.template
+++ b/src/variations/fpm-nginx/etc/nginx/site-opts.d/https.conf.template
@@ -53,5 +53,8 @@ location ~ \.php$ {
     fastcgi_read_timeout $PHP_MAX_EXECUTION_TIME;
 }
 
+# trusted proxy configuration
+include /etc/nginx/trusted-proxy/${TRUSTED_PROXY}.conf;
+
 # additional config
 include /etc/nginx/server-opts.d/*.conf;
\ No newline at end of file
diff --git a/src/variations/fpm-nginx/etc/nginx/server-opts.d/remoteip.conf b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/cloudflare.conf
similarity index 79%
rename from src/variations/fpm-nginx/etc/nginx/server-opts.d/remoteip.conf
rename to src/variations/fpm-nginx/etc/nginx/trusted-proxy/cloudflare.conf
index 22c36bf65..c99d3aea1 100644
--- a/src/variations/fpm-nginx/etc/nginx/server-opts.d/remoteip.conf
+++ b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/cloudflare.conf
@@ -1,13 +1,17 @@
 ##
-# Real IP Addresses
+# Cloudflare - Trusted Proxy
 ##
 
-# Configure docker networks
+# Configure docker networks and loopback addresses
 set_real_ip_from 10.0.0.0/8;
 set_real_ip_from 172.16.0.0/12;
 set_real_ip_from 192.168.0.0/16;
+set_real_ip_from 127.0.0.1/8;
+set_real_ip_from ::1;
+set_real_ip_from fd00::/8;
 
-# CloudFlare
+# Allow Cloudflare's IP addresses
+# IP source: https://www.cloudflare.com/ips/
 set_real_ip_from 173.245.48.0/20;
 set_real_ip_from 103.21.244.0/22;
 set_real_ip_from 103.22.200.0/22;
diff --git a/src/variations/fpm-nginx/etc/nginx/trusted-proxy/local.conf b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/local.conf
new file mode 100644
index 000000000..86563705e
--- /dev/null
+++ b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/local.conf
@@ -0,0 +1,14 @@
+##
+# Local - Trusted Proxy
+##
+
+# Configure docker networks and loopback addresses
+set_real_ip_from 10.0.0.0/8;
+set_real_ip_from 172.16.0.0/12;
+set_real_ip_from 192.168.0.0/16;
+set_real_ip_from 127.0.0.1/8;
+set_real_ip_from ::1;
+set_real_ip_from fd00::/8;
+
+# Set RealIP header
+real_ip_header X-Forwarded-For;
\ No newline at end of file
diff --git a/src/variations/fpm-nginx/etc/nginx/trusted-proxy/off.conf b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/off.conf
new file mode 100644
index 000000000..8dc31e72c
--- /dev/null
+++ b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/off.conf
@@ -0,0 +1 @@
+# Include nothing when TRUSTED_PROXY is set to off
\ No newline at end of file
diff --git a/src/variations/fpm-nginx/etc/nginx/trusted-proxy/sucuri.conf b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/sucuri.conf
new file mode 100644
index 000000000..11aedd1c0
--- /dev/null
+++ b/src/variations/fpm-nginx/etc/nginx/trusted-proxy/sucuri.conf
@@ -0,0 +1,22 @@
+##
+# Sucuri - Trusted Proxy
+##
+
+# Configure docker networks and loopback addresses
+set_real_ip_from 10.0.0.0/8;
+set_real_ip_from 172.16.0.0/12;
+set_real_ip_from 192.168.0.0/16;
+set_real_ip_from 127.0.0.1/8;
+set_real_ip_from ::1;
+set_real_ip_from fd00::/8;
+
+# Allow Sucuri's IP addresses
+# IP source: https://docs.sucuri.net/website-firewall/sucuri-firewall-troubleshooting-guide/
+set_real_ip_from 192.88.134.0/23;
+set_real_ip_from 185.93.228.0/22;
+set_real_ip_from 66.248.200.0/22;
+set_real_ip_from 2a02:fe80::/29;
+set_real_ip_from 208.109.0.0/22;
+
+# Set RealIP header
+real_ip_header X-Forwarded-For;
\ No newline at end of file
diff --git a/src/variations/frankenphp/Dockerfile b/src/variations/frankenphp/Dockerfile
index f9c1ed677..2034e6f6d 100644
--- a/src/variations/frankenphp/Dockerfile
+++ b/src/variations/frankenphp/Dockerfile
@@ -27,7 +27,8 @@ RUN set -eux; \
 		/etc/frankenphp/ssl-mode \
         /etc/frankenphp/log-level \
         /etc/frankenphp/auto-https \
-        /etc/frankenphp/caddyfile.d; \
+        /etc/frankenphp/caddyfile.d \
+        /etc/frankenphp/caddyfile-global.d; \
     # Create default index.php
 	echo '<?php phpinfo();' > /var/www/html/public/index.php; \
     # Create symbolic links
@@ -176,6 +177,7 @@ LABEL org.opencontainers.image.title="serversideup/php (frankenphp)" \
     SSL_MODE=off \
     SSL_CERTIFICATE_FILE="/etc/ssl/private/self-signed-web.crt" \
     SSL_PRIVATE_KEY_FILE="/etc/ssl/private/self-signed-web.key" \
+    TRUSTED_PROXY=cloudflare \
     XDG_CONFIG_HOME=/config \
     XDG_DATA_HOME=/data
 
diff --git a/src/variations/frankenphp/etc/frankenphp/Caddyfile b/src/variations/frankenphp/etc/frankenphp/Caddyfile
index 50b2158be..756479417 100644
--- a/src/variations/frankenphp/etc/frankenphp/Caddyfile
+++ b/src/variations/frankenphp/etc/frankenphp/Caddyfile
@@ -11,48 +11,16 @@
 
 	skip_install_trust
 
-	# Match serversideup/php log levels to Caddy global log levels
 	import log-level/global/{$LOG_OUTPUT_LEVEL:info}.caddyfile
 
 	frankenphp {
 		{$FRANKENPHP_CONFIG}
 	}
 
-	servers {
-		# Trust Docker/private networks + loopback + Cloudflare ranges
-		trusted_proxies static \
-10.0.0.0/8 \
-172.16.0.0/12 \
-192.168.0.0/16 \
-127.0.0.1/8 \
-::1 \
-fd00::/8 \
-173.245.48.0/20 \
-103.21.244.0/22 \
-103.22.200.0/22 \
-103.31.4.0/22 \
-141.101.64.0/18 \
-108.162.192.0/18 \
-190.93.240.0/20 \
-188.114.96.0/20 \
-197.234.240.0/22 \
-198.41.128.0/17 \
-162.158.0.0/15 \
-104.16.0.0/13 \
-104.24.0.0/14 \
-172.64.0.0/13 \
-131.0.72.0/22 \
-2400:cb00::/32 \
-2606:4700::/32 \
-2803:f800::/32 \
-2405:b500::/32 \
-2405:8100::/32 \
-2a06:98c0::/29 \
-2c0f:f248::/32
-
-		# Prefer Cloudflare's header; keep XFF as fallback
-		client_ip_headers CF-Connecting-IP X-Forwarded-For
-	}
+	import trusted-proxy/{$TRUSTED_PROXY:cloudflare}.caddyfile
+
+	# Add additional Caddy configuration files from the caddyfile-global.d directory
+	import caddyfile-global.d/*.caddyfile 
 
 	{$CADDY_GLOBAL_OPTIONS}
 }
diff --git a/src/variations/frankenphp/etc/frankenphp/trusted-proxy/cloudflare.caddyfile b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/cloudflare.caddyfile
new file mode 100644
index 000000000..55d6bcdda
--- /dev/null
+++ b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/cloudflare.caddyfile
@@ -0,0 +1,36 @@
+servers {
+	# Trust Docker/private networks + loopback + Cloudflare ranges
+	# IP source: https://www.cloudflare.com/ips/
+	trusted_proxies static \
+10.0.0.0/8 \
+172.16.0.0/12 \
+192.168.0.0/16 \
+127.0.0.1/8 \
+::1 \
+fd00::/8 \
+173.245.48.0/20 \
+103.21.244.0/22 \
+103.22.200.0/22 \
+103.31.4.0/22 \
+141.101.64.0/18 \
+108.162.192.0/18 \
+190.93.240.0/20 \
+188.114.96.0/20 \
+197.234.240.0/22 \
+198.41.128.0/17 \
+162.158.0.0/15 \
+104.16.0.0/13 \
+104.24.0.0/14 \
+172.64.0.0/13 \
+131.0.72.0/22 \
+2400:cb00::/32 \
+2606:4700::/32 \
+2803:f800::/32 \
+2405:b500::/32 \
+2405:8100::/32 \
+2a06:98c0::/29 \
+2c0f:f248::/32
+
+	# Prefer Cloudflare's header; keep XFF as fallback
+	client_ip_headers CF-Connecting-IP X-Forwarded-For
+}
diff --git a/src/variations/frankenphp/etc/frankenphp/trusted-proxy/local.caddyfile b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/local.caddyfile
new file mode 100644
index 000000000..13a870c12
--- /dev/null
+++ b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/local.caddyfile
@@ -0,0 +1,12 @@
+servers {
+	# Trust Docker/private networks + loopback
+	trusted_proxies static \
+10.0.0.0/8 \
+172.16.0.0/12 \
+192.168.0.0/16 \
+127.0.0.1/8 \
+::1 \
+fd00::/8
+
+	client_ip_headers X-Forwarded-For
+}
diff --git a/src/variations/frankenphp/etc/frankenphp/trusted-proxy/off.caddyfile b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/off.caddyfile
new file mode 100644
index 000000000..e41cd9acc
--- /dev/null
+++ b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/off.caddyfile
@@ -0,0 +1 @@
+# Include nothing when TRUSTED_PROXY is set to off
diff --git a/src/variations/frankenphp/etc/frankenphp/trusted-proxy/sucuri.caddyfile b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/sucuri.caddyfile
new file mode 100644
index 000000000..5de970404
--- /dev/null
+++ b/src/variations/frankenphp/etc/frankenphp/trusted-proxy/sucuri.caddyfile
@@ -0,0 +1,18 @@
+servers {
+	# Trust Docker/private networks + loopback + Sucuri ranges
+	# IP source: https://docs.sucuri.net/website-firewall/sucuri-firewall-troubleshooting-guide/
+	trusted_proxies static \
+10.0.0.0/8 \
+172.16.0.0/12 \
+192.168.0.0/16 \
+127.0.0.1/8 \
+::1 \
+fd00::/8 \
+192.88.134.0/23 \
+185.93.228.0/22 \
+66.248.200.0/22 \
+2a02:fe80::/29 \
+208.109.0.0/22
+
+	client_ip_headers X-Forwarded-For
+}

From 9ad2270c858f3092eea4a15c277487d60ce5cf42 Mon Sep 17 00:00:00 2001
From: Bugeac Sergiu <sergiu.a.bugeac@gmail.com>
Date: Tue, 27 Jan 2026 19:01:08 +0200
Subject: [PATCH 2/5] Do not generate SSL if DISABLE_DEFAULT_CONFIG is set
 (#644)

* Config checks for SSL certificate generation

Add checks for DISABLE_DEFAULT_CONFIG and set default SSL file paths.

* Removed comment since the code is readable

---------

Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com>
---
 .../etc/entrypoint.d/5-generate-ssl.sh                    | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/utilities-webservers/etc/entrypoint.d/5-generate-ssl.sh b/src/utilities-webservers/etc/entrypoint.d/5-generate-ssl.sh
index 86f030d18..82c28d374 100644
--- a/src/utilities-webservers/etc/entrypoint.d/5-generate-ssl.sh
+++ b/src/utilities-webservers/etc/entrypoint.d/5-generate-ssl.sh
@@ -3,7 +3,11 @@
 # Usage: 5-generate-ssl.sh
 ###################################################
 # This script generates a self-signed SSL certificate and key for the container.
-script_name="generate-ssl"  
+script_name="generate-ssl"
+
+if [ "$DISABLE_DEFAULT_CONFIG" = "true" ]; then
+    exit 0
+fi
 
 SSL_CERTIFICATE_FILE=${SSL_CERTIFICATE_FILE:-"/etc/ssl/private/self-signed-web.crt"}
 SSL_PRIVATE_KEY_FILE=${SSL_PRIVATE_KEY_FILE:-"/etc/ssl/private/self-signed-web.key"}
@@ -52,4 +56,4 @@ openssl req -x509 \
     -keyout "$SSL_PRIVATE_KEY_FILE" \
     -out "$SSL_CERTIFICATE_FILE" \
     -days 365 >/dev/null 2>&1
-exit 0
\ No newline at end of file
+exit 0

From 595c3b7fc1f51f91e4e2a349cf770457bfbce427 Mon Sep 17 00:00:00 2001
From: Jay Rogers <3174134+jaydrogers@users.noreply.github.com>
Date: Tue, 27 Jan 2026 11:30:17 -0600
Subject: [PATCH 3/5] Refactor Laravel migration script to improve isolation
 handling and database connection checks (#628)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Refactor Laravel migration script to improve isolation handling and database connection checks

- Removed migration isolation argument from test-db-connection script.
- Introduced a helper function for running migrations per database, enhancing clarity and reusability.
- Updated migration flag assembly logic to better manage isolation settings.
- Improved error handling and logging for database connection issues.

* Remove debug log from Laravel migration script to streamline output during migrations

* Update Laravel migration script to change error message from error to warning for version check

* Update PHP base opertating systems. Add Alpine 3.23 support (#638)

PHP repo no longer has images available for alpine3.21 for latest minor versions, this removes 3.21 if its no longer available and adds 3.23 if available

* Update PHP extension installer version to 2.9.27

* Update NGINX version to 1.28.1

* Refactor and improve security headers, file blocks, etc (#631)

* Fix blocking .well-known path for FrankenPHP

* Remove specific endpoint checks because the whole folder should be allowed

* Enhance security configurations across Apache, NGINX, and Caddy by implementing best practices for HTTP headers and file access restrictions. Added protections against clickjacking, MIME type sniffing, and sensitive file exposure while allowing necessary access to well-known URIs as per RFC 8615.

---------

Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com>
Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net>

* Update GitHub Actions to use actions/checkout@v6 in multiple workflows

* Update GitHub Actions to use actions/upload-artifact@v6 for improved artifact handling

* Update GitHub Actions to use actions/download-artifact@v7 for improved artifact handling

* Upgrade FrankenPHP to v1.11.1

* Increase size of GitHub Actions Runners because of memory segmentation fault issues (Thanks Depot! 😅)

* Add security measures to block PHP execution in storage directory (#641)

Implemented restrictions across Apache, NGINX, and FrankenPHP configurations to prevent the execution of PHP files in the /storage directory, addressing potential vulnerabilities related to arbitrary file uploads (GHSA-29cq-5w36-x7w3).

* Refactor Laravel version check and isolation mode handling in automation script

- Updated the logic for enabling isolation mode based on Laravel version, ensuring it only activates for versions 9.38.0 and above.
- Improved error handling and logging for Laravel version detection, providing clearer output when version determination fails.
- Simplified version comparison logic to enhance readability and maintainability.

* Update container info script to include automation status

---------

Co-authored-by: alloylab <trevor@alloylab.com>
Co-authored-by: Marcel Arns <38068686+marns93@users.noreply.github.com>
---
 .../etc/entrypoint.d/0-container-info.sh      |   3 +-
 .../entrypoint.d/50-laravel-automations.sh    | 145 ++++++++++++------
 .../lib/laravel/test-db-connection.php        |  33 +---
 3 files changed, 105 insertions(+), 76 deletions(-)

diff --git a/src/common/etc/entrypoint.d/0-container-info.sh b/src/common/etc/entrypoint.d/0-container-info.sh
index a71de57ca..b92ee2bdb 100644
--- a/src/common/etc/entrypoint.d/0-container-info.sh
+++ b/src/common/etc/entrypoint.d/0-container-info.sh
@@ -55,7 +55,8 @@ Brought to you by serversideup.net
 • Upload Limit:  '"$UPLOAD_LIMIT"'
 
 🔄 Runtime
-• Docker CMD:     '"$DOCKER_CMD"'
+• Automations:   '"$AUTORUN_ENABLED"'
+• Docker CMD:    '"$DOCKER_CMD"'
 '
 
 if [ "$PHP_OPCACHE_STATUS" = "0" ]; then
diff --git a/src/common/etc/entrypoint.d/50-laravel-automations.sh b/src/common/etc/entrypoint.d/50-laravel-automations.sh
index 1e86e0348..3634c0a12 100644
--- a/src/common/etc/entrypoint.d/50-laravel-automations.sh
+++ b/src/common/etc/entrypoint.d/50-laravel-automations.sh
@@ -53,10 +53,6 @@ fi
 ############################################################################
 
 artisan_migrate() {
-    migrate_flags=""
-
-    debug_log "Starting migrations (isolation: $AUTORUN_LARAVEL_MIGRATION_ISOLATION)"
-
     echo "🚀 Clearing Laravel cache before attempting migrations..."
     php "$APP_BASE_DIR/artisan" config:clear
     
@@ -73,7 +69,8 @@ artisan_migrate() {
             ;;
     esac
 
-    # Build migration flags (used for all databases)
+    # Determine if isolation is intended to be used
+    isolation_enabled="false"
     if [ "$AUTORUN_LARAVEL_MIGRATION_ISOLATION" = "true" ]; then
         # Isolation only works in default mode
         if [ "$AUTORUN_LARAVEL_MIGRATION_MODE" != "default" ]; then
@@ -82,14 +79,18 @@ artisan_migrate() {
         fi
         
         # Isolation requires Laravel 9.38.0+
-        if ! laravel_version_is_at_least "9.38.0"; then
-            echo "❌ $script_name: Isolated migrations require Laravel v9.38.0 or above. Detected version: $(get_laravel_version)"
-            return 1
+        if laravel_version_is_at_least "9.38.0"; then
+            isolation_enabled="true"
+            debug_log "Isolation mode enabled (Laravel version check passed)"
+        else
+            echo "⚠️ $script_name: Isolated migrations require Laravel v9.38.0 or above. Detected version: $(get_laravel_version)"
+            echo "   Continuing without isolation mode..."
         fi
-        
-        migrate_flags="$migrate_flags --isolated"
     fi
 
+    # Start assembling migration flags
+    migrate_flags=""
+
     if [ "$AUTORUN_LARAVEL_MIGRATION_FORCE" = "true" ]; then
         migrate_flags="$migrate_flags --force"
     fi
@@ -98,30 +99,55 @@ artisan_migrate() {
         migrate_flags="$migrate_flags --seed"
     fi
 
-    # Determine if multiple databases are specified
+    # Helper function to run migrations for a specific database
+    run_migration_for_db() {
+        db_name="${1:-}"
+        
+        # Build display name and database flag for messages/commands
+        if [ -n "$db_name" ]; then
+            db_display_name="'$db_name'"
+            db_flag="--database=$db_name"
+        else
+            db_display_name="default database"
+            db_flag=""
+        fi
+        
+        # Wait for database connection
+        if ! wait_for_database_connection $db_name; then
+            echo "❌ $script_name: Failed to connect to $db_display_name"
+            return 1
+        fi
+        
+        # Determine if --isolated can be used for this database
+        db_migrate_flags="$migrate_flags"
+        if [ "$isolation_enabled" = "true" ]; then
+            if db_has_migrations_table $db_name; then
+                db_migrate_flags="$db_migrate_flags --isolated"
+                debug_log "Using --isolated flag for $db_display_name"
+            else
+                echo "ℹ️ Skipping --isolated flag for $db_display_name: migrations table not ready (normal for first deployment)"
+                echo "   The --isolated flag will be used on subsequent deployments."
+            fi
+        fi
+        
+        echo "🚀 Running migrations for $db_display_name"
+        php "$APP_BASE_DIR/artisan" $migration_command $db_flag $db_migrate_flags
+    }
+
+    # Run migrations for specified database(s)
     if [ -n "$AUTORUN_LARAVEL_MIGRATION_DATABASE" ]; then
         databases=$(convert_comma_delimited_to_space_separated "$AUTORUN_LARAVEL_MIGRATION_DATABASE")
         database_list=$(echo "$databases" | tr ',' ' ')
         
         for db in $database_list; do
-            # Wait for this specific database to be ready
-            if ! wait_for_database_connection "$db"; then
-                echo "❌ $script_name: Failed to connect to database: $db"
+            if ! run_migration_for_db "$db"; then
                 return 1
             fi
-            
-            echo "🚀 Running migrations for database: $db"
-            php "$APP_BASE_DIR/artisan" $migration_command --database=$db $migrate_flags
         done
     else
-        # Wait for default database connection
-        if ! wait_for_database_connection; then
-            echo "❌ $script_name: Failed to connect to default database"
+        if ! run_migration_for_db; then
             return 1
         fi
-        
-        # Run migration with default database connection
-        php "$APP_BASE_DIR/artisan" $migration_command $migrate_flags
     fi
 }
 
@@ -241,17 +267,16 @@ get_laravel_version() {
     fi
 
     debug_log "Detecting Laravel version..."
-    # Use 2>/dev/null to handle potential PHP warnings
-    artisan_version_output=$(php "$APP_BASE_DIR/artisan" --version 2>/dev/null)
     
-    # Check if command was successful
-    if [ $? -ne 0 ]; then
+    # Capture artisan output
+    if ! artisan_version_output=$(php "$APP_BASE_DIR/artisan" --version 2>/dev/null); then
         echo "❌ $script_name: Failed to execute artisan command" >&2
         return 1
     fi
     
+    debug_log "Raw artisan output: $artisan_version_output"
+    
     # Extract version number using sed (POSIX compliant)
-    # Using a more strict pattern that matches "Laravel Framework X.Y.Z"
     laravel_version=$(echo "$artisan_version_output" | sed -e 's/^Laravel Framework \([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*$/\1/')
     
     # Validate that we got a version number (POSIX compliant regex)
@@ -261,7 +286,7 @@ get_laravel_version() {
         echo "$laravel_version"
         return 0
     else
-        echo "❌ $script_name: Failed to determine Laravel version" >&2
+        echo "❌ $script_name: Failed to determine Laravel version from: $artisan_version_output" >&2
         return 1
     fi
 }
@@ -286,33 +311,55 @@ laravel_version_is_at_least() {
         return 1
     fi
 
-    # Validate required version format
-    if ! echo "$required_version" | grep -Eq '^[0-9]+\.[0-9]+(\.[0-9]+)?$'; then
-        echo "❌ $script_name - Invalid version requirement format: $required_version" >&2
-        return 1
-    fi
-
     current_version=$(get_laravel_version)
     if [ $? -ne 0 ]; then
         echo "❌ $script_name: Failed to get Laravel version" >&2
         return 1
     fi
 
-    # normalize_version() takes a version string and ensures it has 3 parts
-    normalize_version() {
-        echo "$1" | awk -F. '{ print $1"."$2"."(NF>2?$3:0) }'
-    }
+    # Extract version components using cut (POSIX compliant)
+    cur_major=$(echo "$current_version" | cut -d. -f1)
+    cur_minor=$(echo "$current_version" | cut -d. -f2)
+    cur_patch=$(echo "$current_version" | cut -d. -f3)
+
+    req_major=$(echo "$required_version" | cut -d. -f1)
+    req_minor=$(echo "$required_version" | cut -d. -f2)
+    req_patch=$(echo "$required_version" | cut -d. -f3)
 
-    normalized_current=$(normalize_version "$current_version")
-    normalized_required=$(normalize_version "$required_version")
+    # Default patch to 0 if not specified
+    : "${cur_patch:=0}"
+    : "${req_patch:=0}"
 
-    # Use sort -V to get the lower version, then compare it with required version
-    # This works in BusyBox because we only need to check the first line of output
-    lowest_version=$(printf '%s\n%s\n' "$normalized_required" "$normalized_current" | sort -V | head -n1)
-    if [ "$lowest_version" = "$normalized_required" ]; then
-        return 0    # Success: current version is >= required version
+    # Numeric comparison (POSIX arithmetic expansion handles this correctly)
+    # Compare major version
+    if [ "$cur_major" -gt "$req_major" ]; then
+        return 0
+    elif [ "$cur_major" -lt "$req_major" ]; then
+        return 1
+    fi
+
+    # Major versions equal, compare minor
+    if [ "$cur_minor" -gt "$req_minor" ]; then
+        return 0
+    elif [ "$cur_minor" -lt "$req_minor" ]; then
+        return 1
+    fi
+
+    # Minor versions equal, compare patch
+    if [ "$cur_patch" -ge "$req_patch" ]; then
+        return 0
+    fi
+
+    return 1
+}
+
+db_has_migrations_table() {
+    database_arg="${1:-}"
+    
+    if [ -n "$database_arg" ]; then
+        php "$APP_BASE_DIR/artisan" migrate:status --database="$database_arg" > /dev/null 2>&1
     else
-        return 1    # Failure: current version is < required version
+        php "$APP_BASE_DIR/artisan" migrate:status > /dev/null 2>&1
     fi
 }
 
@@ -324,9 +371,9 @@ test_db_connection() {
     # Pass database connection name only if specified (not empty)
     database_arg="${1:-}"
     if [ -n "$database_arg" ]; then
-        php "$AUTORUN_LIB_DIR/laravel/test-db-connection.php" "$APP_BASE_DIR" "$AUTORUN_LARAVEL_MIGRATION_MODE" "$AUTORUN_LARAVEL_MIGRATION_ISOLATION" "$database_arg"
+        php "$AUTORUN_LIB_DIR/laravel/test-db-connection.php" "$APP_BASE_DIR" "$AUTORUN_LARAVEL_MIGRATION_MODE" "$database_arg"
     else
-        php "$AUTORUN_LIB_DIR/laravel/test-db-connection.php" "$APP_BASE_DIR" "$AUTORUN_LARAVEL_MIGRATION_MODE" "$AUTORUN_LARAVEL_MIGRATION_ISOLATION"
+        php "$AUTORUN_LIB_DIR/laravel/test-db-connection.php" "$APP_BASE_DIR" "$AUTORUN_LARAVEL_MIGRATION_MODE"
     fi
 }
 
diff --git a/src/common/etc/entrypoint.d/lib/laravel/test-db-connection.php b/src/common/etc/entrypoint.d/lib/laravel/test-db-connection.php
index e4817fd3b..0c0b52259 100644
--- a/src/common/etc/entrypoint.d/lib/laravel/test-db-connection.php
+++ b/src/common/etc/entrypoint.d/lib/laravel/test-db-connection.php
@@ -5,12 +5,11 @@
  * This script tests if the Laravel application can connect to its configured database.
  * It's designed to be called from shell scripts during container initialization.
  * 
- * Usage: php test-db-connection.php /path/to/app/base/dir [migration_mode] [migration_isolation] [database_connection]
+ * Usage: php test-db-connection.php /path/to/app/base/dir [migration_mode] [database_connection]
  * 
  * Arguments:
- *   app_base_dir    - Path to Laravel application root
- *   migration_mode  - Migration mode: 'default', 'fresh', or 'refresh' (optional, defaults to 'default')
- *   migration_isolation - Whether to run migrations in isolation (optional, defaults to 'false')
+ *   app_base_dir        - Path to Laravel application root
+ *   migration_mode      - Migration mode: 'default', 'fresh', or 'refresh' (optional, defaults to 'default')
  *   database_connection - Name of the database connection to test (optional, defaults to 'default')
  * 
  * Exit codes:
@@ -21,15 +20,14 @@
  */
 
 // Validate arguments
-if ($argc < 2 || $argc > 5) {
-    fwrite(STDERR, "Usage: php test-db-connection.php /path/to/app/base/dir [migration_mode] [migration_isolation] [database_connection]\n");
+if ($argc < 2 || $argc > 4) {
+    fwrite(STDERR, "Usage: php test-db-connection.php /path/to/app/base/dir [migration_mode] [database_connection]\n");
     exit(1);
 }
 
 $appBaseDir = $argv[1];
 $migrationMode = $argc >= 3 ? $argv[2] : 'default';
-$migrationIsolation = $argc >= 4 ? $argv[3] : 'false';
-$databaseConnection = $argc >= 5 ? $argv[4] : null;
+$databaseConnection = $argc >= 4 ? $argv[3] : null;
 
 // Validate migration mode
 $validModes = ['default', 'fresh', 'refresh'];
@@ -38,13 +36,6 @@
     exit(1);
 }
 
-// Validate migration isolation
-$validIsolations = ['true', 'false'];
-if (!in_array($migrationIsolation, $validIsolations)) {
-    fwrite(STDERR, "Error: Invalid migration isolation '{$migrationIsolation}'. Must be one of: " . implode(', ', $validIsolations) . "\n");
-    exit(1);
-}
-
 // Validate that the app base directory exists
 if (!is_dir($appBaseDir)) {
     fwrite(STDERR, "Error: App base directory does not exist: {$appBaseDir}\n");
@@ -126,17 +117,7 @@
             exit(1);
         }
         
-        // For isolated migrations, the database file must exist (even in default mode)
-        if ($migrationIsolation === 'true') {
-            fwrite(STDERR, "SQLite database file does not exist: {$dbPath}\n");
-            fwrite(STDERR, "Isolated migrations require the database file to exist before running.\n");
-            fwrite(STDERR, "Either:\n");
-            fwrite(STDERR, "  1. Create the database (ensure it has read and write permissions for your user): touch {$dbPath}\n");
-            fwrite(STDERR, "  2. Set AUTORUN_LARAVEL_MIGRATION_ISOLATION=false to let migrations create it\n");
-            exit(1);
-        }
-        
-        // Directory exists and is writable - migrations can create the database file (default mode only)
+        // Directory exists and is writable - migrations can create the database file
         fwrite(STDOUT, "SQLite database directory is ready - migrations will create database\n");
         exit(0);
     }

From 096b1ba80983b0f8e863a7ce672728dfa4b8c8f7 Mon Sep 17 00:00:00 2001
From: Arnaud Ritti <77437157+arnaud-ritti@users.noreply.github.com>
Date: Tue, 27 Jan 2026 19:04:36 +0100
Subject: [PATCH 4/5] Add Nightwatch health check script (#572)

* Add Nightwatch health check script

* Add documentation for Laravel Nightwatch

---------

Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com>
Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net>
---
 .../1.laravel/5.nightwatch.md                 | 51 +++++++++++++++++++
 .../usr/local/bin/healthcheck-nightwatch      |  2 +
 2 files changed, 53 insertions(+)
 create mode 100644 docs/content/docs/3.framework-guides/1.laravel/5.nightwatch.md
 create mode 100755 src/common/usr/local/bin/healthcheck-nightwatch

diff --git a/docs/content/docs/3.framework-guides/1.laravel/5.nightwatch.md b/docs/content/docs/3.framework-guides/1.laravel/5.nightwatch.md
new file mode 100644
index 000000000..2d5e82e54
--- /dev/null
+++ b/docs/content/docs/3.framework-guides/1.laravel/5.nightwatch.md
@@ -0,0 +1,51 @@
+---
+head.title: 'Laravel Nightwatch with Docker - Docker PHP - Server Side Up'
+description: 'Learn how to configure Laravel Nightwatch with Docker.'
+layout: docs
+title: Nightwatch
+---
+
+## Laravel Nightwatch with Docker
+Run Laravel Nightwatch by passing the Artisan command as the container's command. Nightwatch is Laravel's observability platform for monitoring application performance, errors, and queries in real-time.
+
+::note
+Before using Nightwatch with Docker, follow the [Laravel Nightwatch setup instructions](https://nightwatch.laravel.com/docs/start-guide) to install and configure the Nightwatch package in your Laravel application.
+::
+
+## Docker Compose example
+
+This example runs Nightwatch as a separate container using the same image as your web service.
+
+**Key points:**
+- Use the same image for both your web and Nightwatch services
+- Set `SIGTERM` as the stop signal for graceful shutdown (especially for `fpm-apache` and `fpm-nginx`)
+- Include a health check to monitor Nightwatch status
+
+```yml [compose.yml]
+services:
+  php:
+    image: my/laravel-app
+
+  nightwatch:
+    image: my/laravel-app
+    command: ["php", "/var/www/html/artisan", "nightwatch:agent"]
+    stop_signal: SIGTERM
+    healthcheck:
+      test: ["CMD", "healthcheck-nightwatch"]
+      start_period: 10s
+```
+
+## How the health check works
+
+The `healthcheck-nightwatch` command runs `php artisan nightwatch:status` to verify that the Nightwatch agent is running and connected. Docker uses this to determine container health and can automatically restart unhealthy containers.
+
+## Advanced configuration
+
+**Graceful shutdown:** The `SIGTERM` signal ensures the Nightwatch agent finishes processing current events before stopping. This is especially important for `fpm-apache` and `fpm-nginx` images.
+
+::tip
+**Multiple processes in one container:** If you're running `fpm-nginx` or `fpm-apache` and you'd like to have everything in a single container, you can [write your own S6 Overlay service script](https://github.com/just-containers/s6-overlay/tree/master#writing-a-service-script){target="_blank"} to properly manage multiple processes in a single container. Learn more about about this in our [Using S6 Overlay guide](/docs/guide/using-s6-overlay).
+::
+
+## Learn More
+- [Laravel Nightwatch Documentation](https://nightwatch.laravel.com/docs/start-guide)
diff --git a/src/common/usr/local/bin/healthcheck-nightwatch b/src/common/usr/local/bin/healthcheck-nightwatch
new file mode 100755
index 000000000..7c21a462c
--- /dev/null
+++ b/src/common/usr/local/bin/healthcheck-nightwatch
@@ -0,0 +1,2 @@
+#!/bin/sh
+php "${APP_BASE_DIR}/artisan" nightwatch:status
\ No newline at end of file

From d8dc11a884f18bdc8652c5d83a0271ba13984102 Mon Sep 17 00:00:00 2001
From: Jay Rogers <jaydrogers@users.noreply.serversideup.net>
Date: Tue, 27 Jan 2026 12:11:02 -0600
Subject: [PATCH 5/5] Update S6 version to v3.2.2.0

---
 src/s6/usr/local/bin/docker-php-serversideup-s6-install | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/s6/usr/local/bin/docker-php-serversideup-s6-install b/src/s6/usr/local/bin/docker-php-serversideup-s6-install
index 417d3f509..a07f0a1a9 100644
--- a/src/s6/usr/local/bin/docker-php-serversideup-s6-install
+++ b/src/s6/usr/local/bin/docker-php-serversideup-s6-install
@@ -9,7 +9,7 @@ set -oue
 # Be sure to set the S6_SRC_URL, S6_SRC_DEP, and S6_DIR
 # environment variables before running this script.
 
-S6_VERSION=v3.2.1.0
+S6_VERSION=v3.2.2.0
 mkdir -p $S6_DIR
 export SYS_ARCH=$(uname -m)
 case "$SYS_ARCH" in