104 lines
No EOL
3.8 KiB
Markdown
104 lines
No EOL
3.8 KiB
Markdown
# ComposeSync
|
|
|
|
[](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. |