robojerk/ComposeSync
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Major improvements: flexible install dir, configurable compose file name for git, enhanced webhook notifications, cross-platform lock, robust rollback, and updated docs.\n\n- Install dir is now user-confirmable and dynamic\n- Added COMPOSE_FILENAME for git stacks\n- Webhook payloads now include git context and rollback events\n- Lock file age check is cross-platform\n- Rollback notifications for success/failure\n- Updated TOML example and documentation\n- Many robustness and UX improvements

Browse source
This commit is contained in:
robojerk 2025-06-25 15:15:40 -07:00
parent f0dba7cc0a
commit 70486907aa
18 changed files with 3788 additions and 1767 deletions
Download patch file Download diff file Expand all files Collapse all files

251
Docs/installation.md
View file

@ -20,113 +20,164 @@ Since ComposeSync runs with Docker group privileges, ensure:
## Prerequisites
Make sure these are installed on your host system:
* **Docker Engine** and **Docker Compose Plugin** (ensure `docker` and `docker compose` commands work)
* **Basic Utilities:** `wget`, `git`, `bash`, `curl`, `diffutils`
```bash
# On Debian/Ubuntu:
sudo apt install wget git bash curl diffutils
```
* **User in Docker Group:** The user you specify during installation must be in the `docker` group
```bash
sudo usermod -aG docker YOUR_USERNAME
# Then log out and back in
```
- Linux system with systemd
- Docker and Docker Compose installed
- User with sudo privileges
- Git and wget (for downloading compose files)
## Installation Steps
1. **Clone this repository:**
```bash
git clone <your-repo-url>
cd composesync
```
### 1. Download and Install
2. **Run the installation script as root:**
```bash
sudo ./install.sh
```
The script will:
- Ask for the username to run ComposeSync
- Verify the user exists and is in the docker group
- Create necessary directories and set permissions
- Set up the systemd service
- Create a default configuration
3. **Configure your stacks in `/opt/composesync/.env`:**
```bash
sudo nano /opt/composesync/.env
```
Example configuration:
```env
# Base directory for stacks
COMPOSESYNC_BASE_DIR=/opt/composesync/stacks
# Number of versions to keep (default: 10)
KEEP_VERSIONS=10
# Update interval in seconds (default: 3600)
UPDATE_INTERVAL_SECONDS=3600
# Update mode (notify_only or notify_and_apply)
UPDATE_MODE=notify_and_apply
# Stack configurations
STACKS=1
STACK_1_NAME=immich
STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
STACK_1_PATH=/opt/composesync/stacks/immich
STACK_1_TOOL=wget
STACK_1_INTERVAL=86400
STACK_1_KEEP_VERSIONS=10
```
4. **Create stack directories:**
```bash
sudo mkdir -p /opt/composesync/stacks/immich
sudo chown YOUR_USERNAME:docker /opt/composesync/stacks/immich
```
5. **Restart the service to apply changes:**
```bash
sudo systemctl restart composesync
```
## How It Works
ComposeSync runs as a systemd service and monitors your configured stacks for updates. When changes are detected, it:
1. Creates a backup of the current configuration
2. Downloads the new configuration
3. Applies your custom overrides
4. Updates the stack if in `notify_and_apply` mode
5. Maintains versioned copies of configurations
## Directory Structure
```bash
# Clone or download ComposeSync
git clone https://github.com/your-repo/ComposeSync.git
cd ComposeSync
# Run the installation script
sudo ./install.sh
```
/opt/composesync/
├── update-agent.sh
├── .env
└── stacks/
├── immich/
│ ├── docker-compose.yml
│ ├── docker-compose.override.yml
│ ├── compose-*.yml.bak
│ └── backups/
└── portainer/
├── docker-compose.yml
├── docker-compose.override.yml
├── compose-*.yml.bak
└── backups/
The installation script will:
- Create the `/opt/composesync` directory
- Copy scripts and configuration files
- Create a systemd service
- Set up proper permissions
### 2. Configure Your Stacks
#### TOML Configuration (Recommended)
Create your configuration file:
```bash
sudo nano /opt/composesync/config.toml
```
Example configuration:
```toml
# Global settings
[global]
UPDATE_INTERVAL_SECONDS = 3600 # Check every hour
KEEP_VERSIONS = 10
DRY_RUN = false
# Stack configurations
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"
[dev-app]
URL = "https://github.com/user/dev-app.git"
PATH = "/opt/composesync/stacks/dev-app"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "develop"
INTERVAL = 1800 # Check every 30 minutes
```
#### Legacy .env Configuration
If you prefer the legacy .env format:
```bash
sudo nano /opt/composesync/.env
```
Example configuration:
```env
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10
DRY_RUN=false
STACKS=2
STACK_1_NAME=immich
STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
STACK_1_PATH=/opt/composesync/stacks/immich
STACK_1_TOOL=wget
STACK_2_NAME=dev-app
STACK_2_URL=https://github.com/user/dev-app.git
STACK_2_PATH=/opt/composesync/stacks/dev-app
STACK_2_TOOL=git
STACK_2_GIT_SUBPATH=docker/docker-compose.yml
STACK_2_GIT_REF=develop
```
### 3. Create Stack Directories
Create directories for your stacks:
```bash
# For each stack in your configuration
sudo mkdir -p /opt/composesync/stacks/immich
sudo mkdir -p /opt/composesync/stacks/dev-app
# Set proper ownership
sudo chown -R $USER:docker /opt/composesync/stacks/
```
### 4. Create Override Files (Optional)
Create `docker-compose.override.yml` files for your customizations:
```bash
sudo nano /opt/composesync/stacks/immich/docker-compose.override.yml
```
Example override:
```yaml
version: '3.8'
services:
immich-server:
environment:
- DATABASE_URL=postgresql://user:pass@localhost:5432/immich
volumes:
- /path/to/photos:/photos
```
### 5. Start the Service
```bash
# Start ComposeSync
sudo systemctl start composesync
# Enable it to start on boot
sudo systemctl enable composesync
# Check the status
sudo systemctl status composesync
```
### 6. Verify Installation
Check the logs to ensure everything is working:
```bash
# View real-time logs
sudo journalctl -u composesync -f
# Check recent logs
sudo journalctl -u composesync -n 50
```
## Configuration Files
After installation, you'll have these files:
- `/opt/composesync/update-agent.sh` - Main update script
- `/opt/composesync/config-parser.sh` - Configuration parser
- `/opt/composesync/config.toml` - TOML configuration (recommended)
- `/opt/composesync/.env` - Legacy .env configuration
- `/opt/composesync/config.toml.example` - Example TOML configuration
## Next Steps
After installation, you should:
1. **[Configure your stacks](configuration.md)** - Set up your Docker Compose stacks
2. **[Create override files](multi-stack.md#creating-override-files)** - Add your customizations
3. **[Test with dry-run mode](dry-run.md)** - Verify your configuration
4. **[Set up monitoring](monitoring.md)** - Monitor the service logs
- **[Configuration Reference](configuration.md)** - All configuration options
- **[Multi-Stack Setup](multi-stack.md)** - Managing multiple stacks
- **[Safety Features](safety-features.md)** - Rollback and error handling
- **[Monitoring](monitoring.md)** - Logs and service management