diff --git a/TEMPLATES.md b/TEMPLATES.md index d2404e8..3869d64 100644 --- a/TEMPLATES.md +++ b/TEMPLATES.md @@ -708,6 +708,47 @@ docker compose up -d --build || _die "Failed to start services" echo "Installation of ${CONTAINER_NAME} complete" ``` +### External Volumes for Backup/Restore Compatibility + +When using Docker Compose with Dropshell's backup/restore system, mark volumes as `external: true` in your `docker-compose.yml`. This prevents docker-compose from trying to manage volumes that Dropshell creates during restore operations. + +**docker-compose.yml:** +```yaml +services: + myapp: + image: myimage:latest + volumes: + - ${DATA_VOLUME}:/data + - ${CONFIG_VOLUME}:/config + +volumes: + mydata: + name: ${DATA_VOLUME} + external: true + myconfig: + name: ${CONFIG_VOLUME} + external: true +``` + +**install.sh** - Create volumes before docker-compose runs: +```bash +#!/bin/bash +source "${AGENT_PATH}/common.sh" +_check_required_env_vars "CONTAINER_NAME" "DATA_VOLUME" "CONFIG_VOLUME" + +# Create volumes if they don't exist (required since docker-compose uses external: true) +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" +``` + +Without `external: true`, docker-compose will warn during restore: +``` +volume "mydata" already exists but was not created by Docker Compose +``` + ### Docker Compose Best Practices 1. **Always include `--build`** in install.sh when using custom images @@ -715,6 +756,7 @@ echo "Installation of ${CONTAINER_NAME} complete" 3. **Define service names** consistently with `CONTAINER_NAME` 4. **Handle cleanup** properly in stop.sh and uninstall.sh using `docker compose 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 ## Validating Templates