public/dropshell
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update TEMPLATES.md
All checks were successful
Build-Test-Publish / build (linux/arm64) (push) Successful in 20s
Details
Build-Test-Publish / build (linux/amd64) (push) Successful in 1m25s
Details

Browse Source
This commit is contained in:
j
2026-02-27 10:18:49 +13:00
parent 200d438908
commit 58e54db592
1 changed files with 27 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
TEMPLATES.md
View File

@@ -308,7 +308,7 @@ docker logs "$CONTAINER_NAME" "$@"
**Note:** If your service uses docker compose with multiple containers, prefer `docker compose logs` instead: **Note:** If your service uses docker compose with multiple containers, prefer `docker compose logs` instead:
```bash ```bash
docker compose -f "${SERVICE_PATH}/docker-compose.yml" logs "$@" docker compose -p "${CONTAINER_NAME}" logs "$@"
``` ```
**Usage:** **Usage:**
@@ -683,16 +683,36 @@ fi
When creating templates that use Docker Compose: 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 ### 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`: When using `docker compose` with custom images (defined with `build:` in your compose file), **always use the `--build` flag** in your `install.sh`:
```bash ```bash
# CORRECT - Forces rebuild of images during installation # 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 # WRONG - May use stale cached images
docker compose up -d docker compose -p "${CONTAINER_NAME}" up -d
``` ```
This ensures that: This ensures that:
@@ -711,10 +731,10 @@ _check_required_env_vars "CONTAINER_NAME"
_check_docker_installed || _die "Docker test failed" _check_docker_installed || _die "Docker test failed"
# Stop any existing containers # Stop any existing containers
docker compose down || true docker compose -p "${CONTAINER_NAME}" down || true
# Start with rebuild to ensure fresh images # 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" 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 docker volume create "${CONFIG_VOLUME}" 2>/dev/null || true
# Start the containers # 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: 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 1. **Always include `--build`** in install.sh when using custom images
2. **Use `.env` files** for configuration that Docker Compose can read 2. **Use `.env` files** for configuration that Docker Compose can read
3. **Define service names** consistently with `CONTAINER_NAME` 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 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 6. **Mark volumes as `external: true`** when using Dropshell backup/restore to avoid warnings