ComposeSync/README.md

ComposeSync

Automated Docker Compose update agent that downloads and applies updates to docker-compose.yml files from remote sources while preserving your custom overrides.

ComposeSync is designed to run directly on the host system as a systemd service, not in a container. This provides better performance, reliability, and direct access to the Docker daemon.

TLDR

ComposeSync automatically keeps your Docker Compose stacks up to date by:

1. Downloading the latest docker-compose.yml from a URL or Git repo
2. Preserving your docker-compose.override.yml customizations
3. Applying updates safely with automatic rollback on failure

Quick Example:

# Install (will ask for confirmation of installation directory)
sudo ./install.sh

# Configure your stack (TOML format - recommended)
sudo nano /path/to/installation/config.toml

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

# Stack configuration
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/path/to/installation/stacks/immich"
TOOL = "wget"

Or for Git repositories:

[immich]
URL = "https://github.com/immich-app/immich.git"
PATH = "/path/to/installation/stacks/immich"
TOOL = "git"
GIT_SUBPATH = "deployments/docker"
GIT_REF = "main"

Legacy .env format is also supported:

STACKS=1
STACK_1_NAME=immich
STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
STACK_1_PATH=/path/to/installation/stacks/immich
STACK_1_TOOL=wget

# Create your override file
sudo mkdir -p /path/to/installation/stacks/immich
sudo nano /path/to/installation/stacks/immich/docker-compose.override.yml

# Start the service
sudo systemctl start composesync

That's it! ComposeSync will now automatically update your Immich stack every hour while preserving your customizations.

Features

• Multi-Stack Support - Manage multiple Docker Compose stacks
• Multiple Sources - HTTP/HTTPS URLs and Git repositories
• Override Preservation - Keeps your docker-compose.override.yml safe
• Automatic Rollback - Reverts failed updates automatically
• Versioned History - Easy rollback to previous versions
• Dry-Run Mode - Test updates without applying them
• Webhook Notifications - Get notified of updates and errors
• Lock File Protection - Prevents concurrent updates
• Multiple Compose Files - Handle complex stacks with multiple YAML files

Documentation

• Installation Guide - Detailed setup instructions
• Configuration Reference - All configuration options
• Multi-Stack Setup - Managing multiple stacks
• Git Repository Setup - Using Git sources
• Safety Features - Rollback, locks, and error handling
• Webhook Notifications - Setting up notifications
• Dry-Run Mode - Testing configurations safely
• Watchtower Integration - Working with Watchtower
• Troubleshooting - Common issues and solutions

Quick Links

• View Logs: sudo journalctl -u composesync -f
• Service Control: Start, stop, restart
• Manual Rollback: Revert to previous version
• Configuration File: /opt/composesync/.env

Contributing

Feel free to submit issues and enhancement requests!

This project is licensed under the MIT License - see the LICENSE file for details.