Prevent S6 startup races: services wait for their config oneshots and depend on base

docs/content/docs/6.customizing-the-image/3.adding-your-own-start-up-scripts.md

@@ -151,6 +151,12 @@ In the above file, we're copying our "one-shot" scripts to the `/etc/entrypoint.
 
 The magic happens when we run `docker-php-serversideup-s6-init`. This script will move all our scripts from the `/etc/entrypoint.d` directory to the `/etc/s6-overlay/scripts` directory and set the correct dependencies for our S6 services.
 
-You can now reference our script names as dependencies in your own S6 service.
+You can now reference our script names as dependencies in your own S6 service. Declare each dependency as an empty file in your service's `dependencies.d` directory. S6 Overlay recommends every service also depend on `base` to prevent race conditions during container start up.
+
+```sh
+mkdir -p /etc/s6-overlay/s6-rc.d/my-s6-service/dependencies.d
+touch /etc/s6-overlay/s6-rc.d/my-s6-service/dependencies.d/base
+touch /etc/s6-overlay/s6-rc.d/my-s6-service/dependencies.d/10-init-webserver-config
+```
 
 :u-button{to="https://github.com/just-containers/s6-overlay" label="Learn more about S6 Overlay" aria-label="Learn more about S6 Overlay" 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" target="_blank"}

src/s6/usr/local/bin/docker-php-serversideup-s6-init

@@ -27,6 +27,17 @@ if [ "$(id -u)" -ne 0 ]; then
     exit 1
 fi
 
+# Services are skipped when they are not part of the image (e.g. nginx on an Apache image)
+add_dependency() {
+  service="$1"
+  dependency="$2"
+
+  if [ -d "${S6_HOME}/s6-rc.d/${service}" ]; then
+    mkdir -p "${S6_HOME}/s6-rc.d/${service}/dependencies.d"
+    touch "${S6_HOME}/s6-rc.d/${service}/dependencies.d/${dependency}"
+  fi
+}
+
 for file in "$ENTRYPOINT_DIR"/*.sh; do
   [ -e "$file" ] || continue # Skip if no files match
 
@@ -47,6 +58,9 @@ for file in "$ENTRYPOINT_DIR"/*.sh; do
     # Place empty file in contents.d
     touch "${S6_HOME}/s6-rc.d/user/contents.d/${script_name}"
 
+    # S6 Overlay recommends every user service depend on "base" to prevent race conditions
+    add_dependency "$script_name" base
+
     # Ensure the ${S6_HOME}/scripts/ directory exists
     mkdir -p "${S6_HOME}/scripts"
 
@@ -65,10 +79,7 @@ for file in "$ENTRYPOINT_DIR"/*.sh; do
 
     # Check if the previous script is not the current script and set as dependency
     if [ "$previous_script_name" != "$script_name" ] && [ -n "$previous_script_name" ]; then
-      dependencies_file="${S6_HOME}/s6-rc.d/${script_name}/dependencies"
-      touch "$dependencies_file"
-      echo "$previous_script_name" >> "$dependencies_file"
-      chmod 644 "$dependencies_file"
+      add_dependency "$script_name" "$previous_script_name"
     fi
 
     # Set the previous file for the next loop
@@ -77,4 +88,10 @@ for file in "$ENTRYPOINT_DIR"/*.sh; do
     echo "Skipping ${script_name} because it already exists at ${S6_HOME}/scripts/${script_name}"
   fi
 
-done
+done
+
+# Long-running services must wait for the oneshots that write their config, otherwise
+# they race the oneshots when the container runs as root (see #689).
+add_dependency php-fpm 5-fpm-pool-user
+add_dependency nginx 10-init-webserver-config
+add_dependency apache2 10-init-webserver-config