ComposeSync/Docs/multi-stack.md

Multi-Stack Configuration

This guide covers how to configure and manage multiple Docker Compose stacks with ComposeSync.

Basic Multi-Stack Setup

You can manage multiple stacks by adding configurations to your .env file. Each stack is configured with a numbered prefix:

# Number of stacks to manage
STACKS=2

# Stack 1: Immich
STACK_1_NAME=immich
STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
STACK_1_PATH=/opt/composesync/stacks/immich
STACK_1_TOOL=wget
STACK_1_INTERVAL=86400

# Stack 2: Portainer
STACK_2_NAME=portainer
STACK_2_URL=https://github.com/portainer/portainer-compose.git
STACK_2_PATH=/opt/composesync/stacks/portainer
STACK_2_TOOL=git
STACK_2_INTERVAL=43200

Multiple Compose Files

For stacks that use multiple compose files (like Immich), you can specify them in the configuration:

STACKS=1

# Immich stack with multiple compose files
STACK_1_NAME=immich
STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
STACK_1_PATH=/opt/composesync/stacks/immich
STACK_1_TOOL=wget
STACK_1_INTERVAL=86400
STACK_1_KEEP_VERSIONS=10

# Additional compose files (numbered)
STACK_1_EXTRA_FILES_1=https://raw.githubusercontent.com/immich-app/immich/refs/heads/main/docker/hwaccel.ml.yml
STACK_1_EXTRA_FILES_2=https://raw.githubusercontent.com/immich-app/immich/refs/heads/main/docker/hwaccel.transcoding.yml
STACK_1_EXTRA_FILES_3=https://raw.githubusercontent.com/immich-app/immich/refs/heads/main/docker/prometheus.yml

# Custom file ordering (optional)
STACK_1_EXTRA_FILES_ORDER=3,1,2

If STACK_1_EXTRA_FILES_ORDER is set, extra files will be processed in the specified order (e.g., 3,1,2). Otherwise, files are processed in numeric order (1,2,3,...).

Complete Example: Immich Stack

Here's a complete example of setting up Immich with all its compose files:

1. Configure the stack in .env

STACKS=1

# Main compose file
STACK_1_NAME=immich
STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
STACK_1_PATH=/opt/composesync/stacks/immich
STACK_1_TOOL=wget
STACK_1_INTERVAL=86400
STACK_1_KEEP_VERSIONS=10

# Additional compose files (one per line, numbered)
# 1. Hardware acceleration for machine learning
STACK_1_EXTRA_FILES_1=https://raw.githubusercontent.com/immich-app/immich/refs/heads/main/docker/hwaccel.ml.yml
# 2. Hardware acceleration for video transcoding
STACK_1_EXTRA_FILES_2=https://raw.githubusercontent.com/immich-app/immich/refs/heads/main/docker/hwaccel.transcoding.yml
# 3. Prometheus monitoring
STACK_1_EXTRA_FILES_3=https://raw.githubusercontent.com/immich-app/immich/refs/heads/main/docker/prometheus.yml

The script will process these files in order (1, 2, 3) when running docker compose.

2. Create your override file

sudo mkdir -p /opt/composesync/stacks/immich
sudo nano /opt/composesync/stacks/immich/docker-compose.override.yml

Note: You must create the docker-compose.override.yml file manually. ComposeSync will not create it for you. This file should contain your customizations and will be preserved during updates.

3. Add your customizations

# docker-compose.override.yml
services:
  immich-server:
    environment:
      - IMMICH_SERVER_URL=http://immich-server:2283
      - IMMICH_API_URL_EXTERNAL=https://immich.raines.xyz/api
      - IMMICH_WEB_URL=https://immich.raines.xyz
    networks:
      - npm_network
      - immich-backend
    devices:
      - /dev/dri:/dev/dri

  redis:
    networks:
      - immich-backend
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 5s
      retries: 3

  database:
    networks:
      - immich-backend
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d ${DB_DATABASE_NAME} -U ${DB_USERNAME}"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_interval: 30s

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-openvino
    environment:
      - OPENVINO_DEVICE=GPU
      - OPENVINO_GPU_DEVICE_ID=0
    devices:
      - /dev/dri:/dev/dri
    device_cgroup_rules:
      - 'c 189:* rmw'
    volumes:
      - /dev/bus/usb:/dev/bus/usb
    networks:
      - immich-backend

volumes:
  cifs_immich:
    external: true

networks:
  npm_network:
    external: true
  immich-backend:
    name: immich-backend

4. Set permissions

sudo chown -R YOUR_USERNAME:docker /opt/composesync/stacks/immich

5. Restart the service

sudo systemctl restart composesync

How Multiple Files Work

The service will now:

1. Download the main docker-compose.yml
2. Download all additional compose files specified in STACK_1_EXTRA_FILES
3. Apply your docker-compose.override.yml
4. Use all files when running docker compose up

When running commands manually, you'll need to specify all the files:

docker compose -f docker-compose.yml \
  -f hwaccel.ml.yml \
  -f hwaccel.transcoding.yml \
  -f prometheus.yml \
  -f docker-compose.override.yml \
  up -d

Stack-Specific Settings

Each stack can have its own settings that override the global configuration:

# Global settings
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10

# Stack 1: Check every 12 hours, keep 15 versions
STACK_1_INTERVAL=43200
STACK_1_KEEP_VERSIONS=15

# Stack 2: Check every 6 hours, keep 5 versions
STACK_2_INTERVAL=21600
STACK_2_KEEP_VERSIONS=5

Creating Override Files

For each stack, you should create a docker-compose.override.yml file in the stack directory. This file contains your customizations and will be preserved during updates.

Example override file structure:

services:
  your-service:
    environment:
      - CUSTOM_VAR=value
    networks:
      - your-network
    volumes:
      - /host/path:/container/path

networks:
  your-network:
    external: true

Managing Multiple Stacks

Viewing All Stacks

ls -la /opt/composesync/stacks/

Checking Stack Status

# Check if a specific stack is running
docker compose -f /opt/composesync/stacks/immich/docker-compose.yml ps

# Check all stacks
for stack in /opt/composesync/stacks/*/; do
  echo "=== $(basename $stack) ==="
  docker compose -f "$stack/docker-compose.yml" ps
done

Manual Updates

# Update a specific stack manually
sudo systemctl restart composesync

# Or run the update script directly
sudo -u composesync /opt/composesync/update-agent.sh

Best Practices

1. Use descriptive stack names - Make them easy to identify
2. Group related stacks - Keep similar applications together
3. Set appropriate intervals - More critical stacks can check more frequently
4. Use stack-specific settings - Override global settings when needed
5. Test with dry-run mode - Verify configurations before applying
6. Monitor logs - Keep an eye on update activities