robojerk/ComposeSync
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ComposeSync/Docs/watchtower.md

8.9 KiB
Raw Blame History

Watchtower Integration

This guide explains how ComposeSync works with Watchtower and provides recommendations for using both tools together.

Overview

ComposeSync and Watchtower are complementary tools that serve different purposes:

  • ComposeSync: Updates Docker Compose configuration files
  • Watchtower: Updates Docker container images

Key Differences

Feature ComposeSync Watchtower
Purpose Updates compose files Updates container images
Scope Configuration changes Image updates
Method Downloads new compose files Pulls new images
Safety Preserves overrides, rollback on failure Automatic image updates
Control Version-controlled updates Real-time updates

When to Use Each Tool

Use ComposeSync When:

  • You want to update application configurations
  • You need to preserve custom overrides
  • You want version-controlled updates
  • You're managing complex multi-service stacks
  • You need rollback capabilities

Use Watchtower When:

  • You want automatic image updates
  • You're running simple containers
  • You don't need configuration changes
  • You want real-time updates
  • You're using latest tags

Integration Strategies

Strategy 1: ComposeSync Only (Recommended)

Use ComposeSync for both configuration and image updates:

# Global settings
[global]
UPDATE_INTERVAL_SECONDS = 3600
KEEP_VERSIONS = 10
DRY_RUN = false

# Stack with specific image versions
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"

Benefits:

  • Full control over updates
  • Configuration and images updated together
  • Automatic rollback on failures
  • Preserves your customizations

Strategy 2: Watchtower Only

Use Watchtower for automatic image updates:

# docker-compose.yml
version: '3.8'
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600
      - WATCHTOWER_CLEANUP=true
    restart: unless-stopped

Benefits:

  • Real-time image updates
  • Simple setup
  • Automatic cleanup

Strategy 3: Hybrid Approach

Use both tools for different purposes:

# ComposeSync for configuration updates
[global]
UPDATE_INTERVAL_SECONDS = 86400  # Daily config updates
KEEP_VERSIONS = 10
DRY_RUN = false

[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"

# Watchtower for image updates
version: '3.8'
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600  # Hourly image updates
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LABEL_ENABLE=true
    restart: unless-stopped

Best Practices

1. Avoid Conflicts

Don't use both tools on the same services - this can cause conflicts and unexpected behavior.

2. Use Specific Image Tags

When using ComposeSync, prefer specific image tags over latest:

# Good: Specific version
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:v1.75.0

# Avoid: Latest tag
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:latest

3. Configure Update Intervals

Set appropriate intervals for each tool:

# ComposeSync: Less frequent config updates
[global]
UPDATE_INTERVAL_SECONDS = 86400  # Daily

[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"

# Watchtower: More frequent image updates
services:
  watchtower:
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600  # Hourly

4. Use Labels for Control

When using Watchtower, use labels to control which containers are updated:

# docker-compose.yml
version: '3.8'
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:v1.75.0
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    restart: unless-stopped

  database:
    image: postgres:15
    labels:
      - "com.centurylinklabs.watchtower.enable=false"  # Don't auto-update
    restart: unless-stopped

Migration Scenarios

From Watchtower to ComposeSync

If you're currently using Watchtower and want to switch to ComposeSync:

  1. Stop Watchtower:

    docker compose down watchtower

  2. Configure ComposeSync:

    [global]
UPDATE_INTERVAL_SECONDS = 3600
KEEP_VERSIONS = 10
DRY_RUN = false

[your-stack]
URL = "https://your-source.com/docker-compose.yml"
PATH = "/opt/composesync/stacks/your-stack"
TOOL = "wget"

  3. Create override file:

    sudo nano /opt/composesync/stacks/your-stack/docker-compose.override.yml

  4. Start ComposeSync:

    sudo systemctl start composesync

From ComposeSync to Watchtower

If you want to switch from ComposeSync to Watchtower:

  1. Stop ComposeSync:

    sudo systemctl stop composesync
sudo systemctl disable composesync

  2. Deploy Watchtower:

    version: '3.8'
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600
      - WATCHTOWER_CLEANUP=true
    restart: unless-stopped

  3. Update your compose files to use latest tags:

    services:
  your-app:
    image: your-app:latest

Troubleshooting

Conflicts Between Tools

If you experience conflicts:

# Check which tool is managing your containers
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# Check ComposeSync logs
sudo journalctl -u composesync -f

# Check Watchtower logs
docker logs watchtower

Unexpected Updates

If containers are updating unexpectedly:

# Check ComposeSync configuration
cat /opt/composesync/config.toml

# Check Watchtower configuration
docker inspect watchtower | grep -A 10 "Env"

# Check container labels
docker inspect your-container | grep -A 5 "Labels"

Performance Issues

If you experience performance issues:

# Check update frequency
grep "UPDATE_INTERVAL_SECONDS" /opt/composesync/config.toml

# Check Watchtower interval
docker inspect watchtower | grep "WATCHTOWER_POLL_INTERVAL"

# Monitor resource usage
docker stats

Recommendations

For Production Environments

Use ComposeSync for production environments because:

  • Better control over updates
  • Automatic rollback on failures
  • Preserves your customizations
  • Version-controlled updates
  • Better monitoring and logging

For Development Environments

Use Watchtower for development environments because:

  • Faster iteration
  • Real-time updates
  • Simpler setup
  • Less configuration overhead

For Mixed Environments

Use the hybrid approach with:

  • ComposeSync for critical production stacks
  • Watchtower for development and testing stacks
  • Clear separation of responsibilities

Example Configurations

Production Setup (ComposeSync Only)

# /opt/composesync/config.toml
[global]
UPDATE_INTERVAL_SECONDS = 86400  # Daily updates
KEEP_VERSIONS = 15
DRY_RUN = false
NOTIFICATION_WEBHOOK_URL = "https://your-webhook.com/endpoint"

[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"

[portainer]
URL = "https://github.com/portainer/portainer-compose.git"
PATH = "/opt/composesync/stacks/portainer"
TOOL = "git"
GIT_SUBPATH = "compose/docker-compose.yml"
GIT_REF = "main"

Development Setup (Watchtower Only)

# docker-compose.yml
version: '3.8'
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=1800  # 30 minutes
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LABEL_ENABLE=true
    restart: unless-stopped

  dev-app:
    image: your-dev-app:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    restart: unless-stopped

Hybrid Setup

# ComposeSync for production stacks
[global]
UPDATE_INTERVAL_SECONDS = 86400
KEEP_VERSIONS = 10

[production-app]
URL = "https://github.com/user/production-app.git"
PATH = "/opt/composesync/stacks/production"
TOOL = "git"
GIT_REF = "main"

# Watchtower for development stacks
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LABEL_ENABLE=true
    restart: unless-stopped

  dev-app:
    image: your-dev-app:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    restart: unless-stopped