From 3fadb31549bac18837e8d3e193bb39d3ec2b34e1 Mon Sep 17 00:00:00 2001
From: lacatoire <louis-arnaud.catoire@external.drivalia.com>
Date: Thu, 27 Nov 2025 16:23:51 +0100
Subject: [PATCH 1/2] doc on docker directories caddy autosave

---
 docs/docker.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs/docker.md b/docs/docker.md
index 23af3fa02..a8c0df77e 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -35,6 +35,68 @@ docker run -it --rm --name my-running-app my-php-app
 For convenience, [a default `Caddyfile`](https://github.com/php/frankenphp/blob/main/caddy/frankenphp/Caddyfile) containing
 useful environment variables is provided in the image.
 
+## ⚠️ Important: Required Caddy storage directories inside Docker
+
+When running FrankenPHP inside Docker, Caddy uses two internal storage directories:
+
+- `/data/caddy` for the certificates, locks, cache
+- `/config/caddy` for the autosave file (`autosave.json`)
+
+These directories are **not created automatically**.
+
+If `/config/caddy` does not exist or is not writable, Caddy will fail to save its adapted configuration and will silently fall back to:
+```
+serving initial configuration
+```
+
+even if your `Caddyfile` is valid.
+
+### Recommended fix (Dockerfile)
+
+Add the following snippet to your Dockerfile **before switching to `www-data`**:
+
+```dockerfile
+RUN mkdir -p /data/caddy/locks \
+    && mkdir -p /config/caddy \
+    && touch /data/caddy/instance.uuid \
+    && chown -R www-data:www-data /data /config /etc/caddy
+```
+
+## Using Docker Compose: important note about the application directory
+
+When using Docker Compose with bind-mounted volumes (e.g. .:/app), Docker mounts the volume after the container starts.
+
+Caddy validates the root directive before the mount happens.
+
+If your application is mounted over /app, this overwrites internal Caddy files and may prevent it from accessing:
+ ```
+- /etc/caddy/Caddyfile
+- /data/caddy
+- /config/caddy
+```
+This results in Caddy failing validation and falling back to the initial configuration, even if everything else is correct.
+
+## Recommendation for Docker Compose users
+
+Do not mount your application into `/app`.
+
+Instead, use a dedicated directory such as: `/srv/app`
+
+
+Example:
+```
+services:
+    app:
+        volumes:
+            - .:/srv/app
+```
+
+And ensure the root directory exists in the image:
+```
+RUN mkdir -p /srv/app/public
+```
+This prevents Docker from overwriting internal Caddy directories and guarantees stable behavior during development.
+
 ## How to Install More PHP Extensions
 
 The [`docker-php-extension-installer`](https://github.com/mlocati/docker-php-extension-installer) script is provided in the base image.

From 47fdb16739e14f309dbacf57f841517e24180aef Mon Sep 17 00:00:00 2001
From: lacatoire <louis-arnaud.catoire@external.drivalia.com>
Date: Thu, 27 Nov 2025 16:33:42 +0100
Subject: [PATCH 2/2] update some phrase

---
 docs/docker.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/docker.md b/docs/docker.md
index a8c0df77e..cd57dcd3c 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -95,7 +95,8 @@ And ensure the root directory exists in the image:
 ```
 RUN mkdir -p /srv/app/public
 ```
-This prevents Docker from overwriting internal Caddy directories and guarantees stable behavior during development.
+This prevents the bind-mount from overwriting internal Caddy directories and guarantees stable behavior during development.
+This setup matches the directory structure used in many production deployments and avoids subtle issues with Caddy startup sequencing.
 
 ## How to Install More PHP Extensions