aottr.dev
Pull-based GitOps-style Docker Compose deployer: polls a (private) Git repo, detects changed stacks and reconciles only the affected
1# compose-sync
2
3A tool to automatically sync and deploy Docker Compose stacks from a git repository, with multi-host support.
4
5## Overview
6
7compose-sync pulls changes from a git repository containing Docker Compose files and only deploys stacks that:
81. Have changed since the last pull
92. Are assigned to the current host
10
11## How It Works
12
131. **Host Detection**: The tool uses the system hostname to identify the current host
142. **Stack Assignment**: Reads `inventory.yml` to determine which stacks should be deployed on this host
153. **Change Detection**: Compares git commits before and after pulling to find changed stacks
164. **Selective Deployment**: Only deploys stacks that both changed AND are assigned to this host
17
18## Repository Structure
19
20Your git repository should have the following structure:
21
22```
23stacks/
24 traefik/compose.yml
25 uptime-kuma/compose.yml
26 home-assistant/compose.yml
27 ...
28
29inventory.yml
30```
31
32The `inventory.yml` file at the root contains all hosts and their assigned stacks. For example:
33
34```yaml
35hosts:
36 vps-1:
37 - traefik
38 - uptime-kuma
39 nas-1:
40 - home-assistant
41 - nextcloud
42```
43
44## Requirements
45
46- Go 1.21 or later
47- Git
48- Docker and Docker Compose
49- A git repository with the structure described above
50
51## Installation
52
53### Using Go Install
54
55```bash
56go install github.com/aottr/compose-sync@latest
57```
58
59### Using Pre-built Binaries
60
61Download the latest release from the [Releases page](https://github.com/aottr/compose-sync/releases).
62
63### Build from Source
64
651. Clone this repository
662. Build the application:
67 ```bash
68 go build -o compose-sync
69 ```
70
71## Configuration
72
731. Copy `config.yml.example` to `config.yml`
742. Edit `config.yml` and set `repo_path` to the local path of your git repository
75
76## Usage
77
78### Basic Usage
79
80```bash
81./compose-sync
82```
83
84This will:
85- Detect the current hostname
86- Pull the latest changes from git
87- Find changed stacks
88- Deploy only changed stacks assigned to this host
89
90### Custom Config Path
91
92```bash
93./compose-sync -config /path/to/config.yml
94```
95
96## Automatic Execution
97
98### Systemd Service and Timer
99
100To run compose-sync automatically using systemd:
101
1021. **Install the binary** (if not already installed):
103 ```bash
104 sudo cp compose-sync /usr/local/bin/
105 ```
106
1072. **Edit the service file** (`compose-sync.service`):
108 - Replace `youruser` with the actual user that should run compose-sync (make sure this user has the correct permissions)
109 - Adjust paths if needed (binary location, config file, etc.)
110
1113. **Copy the service and timer files**:
112 ```bash
113 sudo cp compose-sync.service compose-sync.timer /etc/systemd/system/
114 ```
115
1164. **Reload systemd and enable the timer**:
117 ```bash
118 sudo systemctl daemon-reload
119 sudo systemctl enable compose-sync.timer
120 sudo systemctl start compose-sync.timer
121 ```
122
1235. **Check status**:
124 ```bash
125 sudo systemctl status compose-sync.timer
126 sudo systemctl status compose-sync.service
127 ```
128
1296. **View logs**:
130 ```bash
131 sudo journalctl -u compose-sync.service -f
132 ```
133
134The timer will run compose-sync every 5 minutes. To change the interval, edit `compose-sync.timer` and modify the `OnUnitActiveSec` value.
135
136### Cron Job (Alternative)
137
138To run compose-sync using cron instead of systemd:
139
1401. **Install the cron job**:
141 ```bash
142 crontab -e
143 ```
144 Then add the desired crontab job, for example (every 5min, defaults, logging):
145 ```bash
146 */5 * * * * /usr/local/bin/compose-sync >> /var/log/compose-sync.log 2>&1
147 ```
148
149## License
150
151MIT
152