# ComposeSync

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:**
```bash
# Install (will ask for confirmation of installation directory)
sudo ./install.sh

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

```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:**
```toml
[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:**
```env
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
```

```bash
# 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](Docs/installation.md)** - Detailed setup instructions
- **[Configuration Reference](Docs/configuration.md)** - All configuration options
- **[Multi-Stack Setup](Docs/multi-stack.md)** - Managing multiple stacks
- **[Git Repository Setup](Docs/git-repositories.md)** - Using Git sources
- **[Safety Features](Docs/safety-features.md)** - Rollback, locks, and error handling
- **[Webhook Notifications](Docs/webhooks.md)** - Setting up notifications
- **[Dry-Run Mode](Docs/dry-run.md)** - Testing configurations safely
- **[Watchtower Integration](Docs/watchtower.md)** - Working with Watchtower
- **[Troubleshooting](Docs/troubleshooting.md)** - Common issues and solutions

## Quick Links

- **[View Logs](Docs/monitoring.md#viewing-logs)**: `sudo journalctl -u composesync -f`
- **[Service Control](Docs/monitoring.md#service-control)**: Start, stop, restart
- **[Manual Rollback](Docs/safety-features.md#manual-rollback)**: Revert to previous version
- **[Configuration File](Docs/configuration.md#environment-file)**: `/opt/composesync/.env`

## Contributing

Feel free to submit issues and enhancement requests! 

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.