From 58e54db592ba3401707b127085faeffeff9e793c Mon Sep 17 00:00:00 2001 From: j Date: Fri, 27 Feb 2026 10:18:49 +1300 Subject: [PATCH] Update TEMPLATES.md --- TEMPLATES.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/TEMPLATES.md b/TEMPLATES.md index 4a50932..632a277 100644 --- a/TEMPLATES.md +++ b/TEMPLATES.md @@ -308,7 +308,7 @@ docker logs "$CONTAINER_NAME" "$@" **Note:** If your service uses docker compose with multiple containers, prefer `docker compose logs` instead: ```bash -docker compose -f "${SERVICE_PATH}/docker-compose.yml" logs "$@" +docker compose -p "${CONTAINER_NAME}" logs "$@" ``` **Usage:** @@ -683,16 +683,36 @@ fi When creating templates that use Docker Compose: +### CRITICAL: Always Use `-p "${CONTAINER_NAME}"` with Docker Compose + +**Every `docker compose` command MUST include `-p "${CONTAINER_NAME}"`** to set a unique project name. + +Without this, Docker Compose derives the project name from the directory name. Since all Dropshell templates are deployed to a directory called `template/`, all services end up sharing the same compose project name (`template`). This means when one service runs `docker compose up -d`, it removes containers from other services that aren't in its compose file — silently breaking other running services. + +```bash +# CORRECT - Each service gets its own project namespace +docker compose -p "${CONTAINER_NAME}" up -d +docker compose -p "${CONTAINER_NAME}" stop +docker compose -p "${CONTAINER_NAME}" down +docker compose -p "${CONTAINER_NAME}" logs "$@" +docker compose -p "${CONTAINER_NAME}" pull + +# WRONG - All services share project name "template", causing conflicts +docker compose up -d +docker compose stop +docker compose down +``` + ### Important: Always Build on Install When using `docker compose` with custom images (defined with `build:` in your compose file), **always use the `--build` flag** in your `install.sh`: ```bash # CORRECT - Forces rebuild of images during installation -docker compose up -d --build +docker compose -p "${CONTAINER_NAME}" up -d --build # WRONG - May use stale cached images -docker compose up -d +docker compose -p "${CONTAINER_NAME}" up -d ``` This ensures that: @@ -711,10 +731,10 @@ _check_required_env_vars "CONTAINER_NAME" _check_docker_installed || _die "Docker test failed" # Stop any existing containers -docker compose down || true +docker compose -p "${CONTAINER_NAME}" down || true # Start with rebuild to ensure fresh images -docker compose up -d --build || _die "Failed to start services" +docker compose -p "${CONTAINER_NAME}" up -d --build || _die "Failed to start services" echo "Installation of ${CONTAINER_NAME} complete" ``` @@ -752,7 +772,7 @@ docker volume create "${DATA_VOLUME}" 2>/dev/null || true docker volume create "${CONFIG_VOLUME}" 2>/dev/null || true # Start the containers -docker compose up -d || _die "Failed to start services" +docker compose -p "${CONTAINER_NAME}" up -d || _die "Failed to start services" ``` Without `external: true`, docker-compose will warn during restore: @@ -765,7 +785,7 @@ volume "mydata" already exists but was not created by Docker Compose 1. **Always include `--build`** in install.sh when using custom images 2. **Use `.env` files** for configuration that Docker Compose can read 3. **Define service names** consistently with `CONTAINER_NAME` -4. **Handle cleanup** properly in stop.sh and uninstall.sh using `docker compose down` +4. **Handle cleanup** properly in stop.sh and uninstall.sh using `docker compose -p "${CONTAINER_NAME}" down` 5. **Use named volumes** for persistent data that matches Dropshell conventions 6. **Mark volumes as `external: true`** when using Dropshell backup/restore to avoid warnings