aottr.dev / compose-sync
Pull-based GitOps-style Docker Compose deployer: polls a (private) Git repo, detects changed stacks and reconciles only the affected
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

compose-sync / README.md
at a35354690709928fd48ecf4d466a569805a954fb 3.3 kB view raw view code
A. Ottr feat: add systemd example for automatic exec
a3535469

compose-sync#

A tool to automatically sync and deploy Docker Compose stacks from a git repository, with multi-host support.

Overview#

compose-sync pulls changes from a git repository containing Docker Compose files and only deploys stacks that:

  1. Have changed since the last pull
  2. Are assigned to the current host

Repository Structure#

Your git repository should have the following structure:

stacks/
    traefik/compose.yml
    uptime-kuma/compose.yml
    home-assistant/compose.yml
    ...

inventory.yml

The inventory.yml file at the root contains all hosts and their assigned stacks. For example:

hosts:
  vps-1:
    - traefik
    - uptime-kuma
  nas-1:
    - home-assistant
    - nextcloud

This format is compatible with Ansible inventory structures and provides a centralized view of all host assignments.

Installation#

go install github.com/aottr/compose-sync@latest

Alternatively build from source#

  1. Clone this repository
  2. Build the application: 
    go build -o compose-sync

Configuration#

  1. Copy config.yml.example to config.yml
  2. Edit config.yml and set repo_path to the local path of your git repository

Usage#

Basic Usage#

./compose-sync

This will:

  • Detect the current hostname
  • Pull the latest changes from git
  • Find changed stacks
  • Deploy only changed stacks assigned to this host

Dry Run#

To see what would be deployed without actually deploying:

./compose-sync -dry-run

Custom Config Path#

./compose-sync -config /path/to/config.yml

Systemd Service and Timer (Automatic Execution)#

To run compose-sync automatically using systemd:

  1. Install the binary (if not already installed):

    sudo cp compose-sync /usr/local/bin/

  2. Edit the service file (compose-sync.service):

    • Replace youruser with the actual user that should run compose-sync (make sure this user has the correct permissions)
    • Adjust paths if needed (binary location, config file, etc.)

  3. Copy the service and timer files:

    sudo cp compose-sync.service compose-sync.timer /etc/systemd/system/

  4. Reload systemd and enable the timer:

    sudo systemctl daemon-reload
sudo systemctl enable compose-sync.timer
sudo systemctl start compose-sync.timer

  5. Check status:

    sudo systemctl status compose-sync.timer
sudo systemctl status compose-sync.service

  6. View logs:

    sudo journalctl -u compose-sync.service -f

The timer will run compose-sync every 5 minutes. To change the interval, edit compose-sync.timer and modify the OnUnitActiveSec value.

How It Works#

  1. Host Detection: The tool uses the system hostname to identify the current host
  2. Stack Assignment: Reads inventory.yml to determine which stacks should be deployed on this host
  3. Change Detection: Compares git commits before and after pulling to find changed stacks
  4. Selective Deployment: Only deploys stacks that both changed AND are assigned to this host

Requirements#

  • Go 1.21 or later
  • Git
  • Docker and Docker Compose
  • A git repository with the structure described above

License#

MIT