ComposeSync/Docs/watchtower.md

Watchtower Integration

This guide covers how to use ComposeSync alongside Watchtower and how to configure them to work together effectively.

Understanding the Tools

Watchtower

• Monitors running Docker images and updates them when new versions are available in the registry
• Focuses on updating container images, not compose file configurations
• Works at the container level

ComposeSync

• Monitors remote sources for changes to docker-compose.yml files and applies those changes
• Focuses on updating compose file configurations, not just images
• Works at the compose file level

Recommended Configuration

For stacks managed by ComposeSync, it's recommended to disable Watchtower to prevent conflicts and race conditions.

Disabling Watchtower for ComposeSync Stacks

Add the following to your docker-compose.override.yml:

services:
  your-service:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Example Configuration

# docker-compose.override.yml for a ComposeSync-managed stack
services:
  immich-server:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
  immich-microservices:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
  immich-machine-learning:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Best Practices

1. Use ComposeSync for:

• Applications where the docker-compose.yml configuration evolves
• Complex stacks with multiple services
• Applications that require specific version management
• Stacks with custom configurations and overrides

2. Use Watchtower for:

• Simple, self-contained applications
• Stacks with static docker-compose.yml files
• Applications where only image updates are needed
• Stacks without complex configurations

3. Notification Integration:

• Configure both tools to send notifications to the same webhook
• This provides a unified view of all Docker updates
• Helps track what's being updated and when

Configuration Examples

ComposeSync-Managed Stack (Immich)

# docker-compose.override.yml
services:
  immich-server:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
    environment:
      - IMMICH_SERVER_URL=http://immich-server:2283
    networks:
      - npm_network
      - immich-backend

  redis:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
    networks:
      - immich-backend

  database:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
    networks:
      - immich-backend

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

Watchtower-Managed Stack (Simple App)

# docker-compose.yml
services:
  simple-app:
    image: nginx:latest
    ports:
      - "8080:80"
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

Potential Conflicts

Race Conditions

• Both tools might try to update the same stack simultaneously
• Can lead to inconsistent states
• May cause service interruptions

Configuration Conflicts

• Watchtower might update images while ComposeSync is updating compose files
• Can result in version mismatches
• May break service dependencies

Resource Contention

• Both tools competing for Docker resources
• Can slow down update processes
• May cause timeouts or failures

Monitoring Both Tools

Unified Logging

Monitor both services together:

# Watch ComposeSync logs
sudo journalctl -u composesync -f

# Watch Watchtower logs (if running as container)
docker logs -f watchtower

# Or if running as systemd service
sudo journalctl -u watchtower -f

Webhook Integration

Configure both tools to use the same webhook:

# ComposeSync webhook
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint

# Watchtower webhook (in docker-compose.yml)
environment:
  - WATCHTOWER_NOTIFICATIONS=webhook
  - WATCHTOWER_NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint

Migration Strategy

From Watchtower to ComposeSync

1. Identify stacks to migrate

   • Choose stacks with evolving configurations
   • Select stacks that need custom overrides

2. Configure ComposeSync

   • Add stack configuration to .env
   • Set up override files
   • Test with dry-run mode

3. Disable Watchtower

   • Add labels to disable Watchtower for migrated stacks
   • Keep Watchtower for simple stacks

4. Monitor and verify

   • Check that updates work correctly
   • Verify no conflicts occur

From ComposeSync to Watchtower

1. Identify simple stacks

   • Choose stacks with static configurations
   • Select stacks that only need image updates

2. Remove from ComposeSync

   • Remove stack configuration from .env
   • Clean up stack directories

3. Enable Watchtower

   • Remove Watchtower disable labels
   • Configure Watchtower for the stack

Troubleshooting

Update Conflicts

If you see conflicts between the tools:

1. Check which tool is managing each stack
2. Ensure proper labels are set
3. Monitor logs for race conditions
4. Consider separating responsibilities more clearly

Service Failures

If services fail after updates:

1. Check which tool performed the update
2. Verify the update was applied correctly
3. Check for configuration conflicts
4. Review logs for error messages

Performance Issues

If updates are slow or failing:

1. Check resource usage during updates
2. Verify network connectivity
3. Consider staggering update intervals
4. Monitor for resource contention

Advanced Configuration

Selective Updates

You can configure both tools to update different aspects:

# ComposeSync handles compose file updates
# Watchtower handles image updates for specific services
services:
  app:
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "com.centurylinklabs.watchtower.scope=app"
  
  database:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Update Scheduling

Coordinate update schedules to avoid conflicts:

# ComposeSync: Check every 6 hours
UPDATE_INTERVAL_SECONDS=21600

# Watchtower: Check every 12 hours (different schedule)
# Configure in Watchtower settings

Notification Filtering

Use different webhook endpoints for different tools:

# ComposeSync notifications
NOTIFICATION_WEBHOOK_URL=https://webhook.com/composesync

# Watchtower notifications (separate endpoint)
# Configure in Watchtower settings

This allows you to handle notifications differently based on the source.