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## Repository Structure
12
13Your git repository should have the following structure:
14
15```
16stacks/
17 traefik/compose.yml
18 uptime-kuma/compose.yml
19 home-assistant/compose.yml
20 ...
21
22inventory.yml
23```
24
25The `inventory.yml` file at the root contains all hosts and their assigned stacks. For example:
26
27```yaml
28hosts:
29 vps-1:
30 - traefik
31 - uptime-kuma
32 nas-1:
33 - home-assistant
34 - nextcloud
35```
36
37This format is compatible with Ansible inventory structures and provides a centralized view of all host assignments.
38
39## Installation
40
41```bash
42go install github.com/aottr/compose-sync@latest
43```
44
45#### Alternatively build from source
46
471. Clone this repository
482. Build the application:
49 ```bash
50 go build -o compose-sync
51 ```
52
53## Configuration
54
551. Copy `config.yml.example` to `config.yml`
562. Edit `config.yml` and set `repo_path` to the local path of your git repository
57
58## Usage
59
60### Basic Usage
61
62```bash
63./compose-sync
64```
65
66This will:
67- Detect the current hostname
68- Pull the latest changes from git
69- Find changed stacks
70- Deploy only changed stacks assigned to this host
71
72### Dry Run
73
74To see what would be deployed without actually deploying:
75
76```bash
77./compose-sync -dry-run
78```
79
80### Custom Config Path
81
82```bash
83./compose-sync -config /path/to/config.yml
84```
85
86### Systemd Service and Timer (Automatic Execution)
87
88To run compose-sync automatically using systemd:
89
901. **Install the binary** (if not already installed):
91 ```bash
92 sudo cp compose-sync /usr/local/bin/
93 ```
94
952. **Edit the service file** (`compose-sync.service`):
96 - Replace `youruser` with the actual user that should run compose-sync (make sure this user has the correct permissions)
97 - Adjust paths if needed (binary location, config file, etc.)
98
993. **Copy the service and timer files**:
100 ```bash
101 sudo cp compose-sync.service compose-sync.timer /etc/systemd/system/
102 ```
103
1044. **Reload systemd and enable the timer**:
105 ```bash
106 sudo systemctl daemon-reload
107 sudo systemctl enable compose-sync.timer
108 sudo systemctl start compose-sync.timer
109 ```
110
1115. **Check status**:
112 ```bash
113 sudo systemctl status compose-sync.timer
114 sudo systemctl status compose-sync.service
115 ```
116
1176. **View logs**:
118 ```bash
119 sudo journalctl -u compose-sync.service -f
120 ```
121
122The timer will run compose-sync every 5 minutes. To change the interval, edit `compose-sync.timer` and modify the `OnUnitActiveSec` value.
123
124## How It Works
125
1261. **Host Detection**: The tool uses the system hostname to identify the current host
1272. **Stack Assignment**: Reads `inventory.yml` to determine which stacks should be deployed on this host
1283. **Change Detection**: Compares git commits before and after pulling to find changed stacks
1294. **Selective Deployment**: Only deploys stacks that both changed AND are assigned to this host
130
131## Requirements
132
133- Go 1.21 or later
134- Git
135- Docker and Docker Compose
136- A git repository with the structure described above
137
138## License
139
140MIT
141