feat: improve naming conventions for docker-compose

Author: damienwebdev

.gitignore

@@ -1,2 +1,3 @@
 .env
 .*/
+docker-compose.local.yml

bin/init.sh

@@ -86,8 +86,9 @@ fi
 read -p "Enter a name for your devcontainer (it should be unique per project) [$FOLDER_NAME]: " DEVCONTAINER_NAME
 DEVCONTAINER_NAME="${DEVCONTAINER_NAME:-$FOLDER_NAME}"
 
-## Copy over required docker-compose.yml.
-cp "$DEVCONTAINER_FOLDER/docker-compose.overrides.yml.sample" "$TARGET_DIR/docker-compose.overrides.yml"
+## Copy over required docker-compose files
+cp "$DEVCONTAINER_FOLDER/docker-compose.shared.yml.sample" "$DEVCONTAINER_FOLDER/docker-compose.shared.yml"
+cp "$DEVCONTAINER_FOLDER/docker-compose.local.yml.sample" "$DEVCONTAINER_FOLDER/docker-compose.local.yml"
 echo "services: {}" > "$TARGET_DIR/docker-compose.yml"
 
 ## Copy over devcontainer and set the name and version

devcontainer.json.sample

@@ -3,7 +3,8 @@
   "dockerComposeFile": [
     "docker-compose.yml",
     "magento2-devcontainer/compose/2.4.8/docker-compose.yml",
-    "docker-compose.overrides.yml"
+    "magento2-devcontainer/docker-compose.shared.yml",
+    "magento2-devcontainer/docker-compose.local.yml"
   ],
   "workspaceFolder": "/workspace",
   "service": "php",

docker-compose.local.yml.sample

@@ -0,0 +1 @@
+services: {}

docker-compose.overrides.yml.sample docker-compose.shared.yml.sampledocker-compose.overrides.yml.sample renamed to docker-compose.shared.yml.sample

@@ -0,0 +1,33 @@
+# Docker Compose File Structure
+
+The devcontainer uses multiple Docker Compose files loaded in order, with later files overriding earlier ones:
+
+1. **docker-compose.yml** - Sets the Docker Compose working directory (do not modify)
+2. **compose/{version}/docker-compose.yml** - Version-specific service definitions from devcontainer submodule
+3. **docker-compose.shared.yml** - Shared config for the project (committed to project repo)
+4. **docker-compose.local.yml** - Local developer overrides (gitignored, not committed)
+
+## When to Use Each File
+
+| File                        | Purpose                          | Committed |
+| --------------------------- | -------------------------------- | --------- |
+| `docker-compose.yml`        | Sets Compose working directory   | Yes       |
+| `docker-compose.shared.yml` | Shared project-specific config   | Yes       |
+| `docker-compose.local.yml`  | Personal developer overrides     | No        |
+
+### docker-compose.yml
+
+Do not modify this file. It exists only to set the Docker Compose working directory to `.devcontainer/`. This ensures all relative paths in other compose files resolve correctly.
+
+### docker-compose.shared.yml
+
+- Volume mounts for the workspace
+- Environment variables shared across the team
+- Service configuration specific to the project
+
+### docker-compose.local.yml
+
+- Local volume mounts (e.g., SSH keys, custom configs)
+- Resource limits for your machine
+- Additional services for local debugging
+- Environment variable overrides