Installation Guide

This guide covers the complete installation process for ComposeSync.

Deployment Model

ComposeSync is designed to run directly on the host system as a systemd service, not in a container. This provides:

Direct access to the Docker daemon via /var/run/docker.sock
Better performance and reliability
Standard systemd service management
Native file system access for backups and versioning

Security Considerations

Since ComposeSync runs with Docker group privileges, ensure:

Only trusted users have access to the ComposeSync configuration
The service user is properly restricted
Regular security updates are applied
Monitor logs for any suspicious activity

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

# 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
```
sudo usermod -aG docker YOUR_USERNAME
# Then log out and back in
```

Installation Steps

Clone this repository:

git clone <your-repo-url>
cd composesync

Run the installation script as root:
```
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

Configure your stacks in /opt/composesync/.env:

sudo nano /opt/composesync/.env

Example configuration:

# 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

Create stack directories:

sudo mkdir -p /opt/composesync/stacks/immich
sudo chown YOUR_USERNAME:docker /opt/composesync/stacks/immich

Restart the service to apply changes:
```
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:

Creates a backup of the current configuration
Downloads the new configuration
Applies your custom overrides
Updates the stack if in notify_and_apply mode
Maintains versioned copies of configurations

Directory Structure

/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/

Next Steps

After installation, you should:

Configure your stacks - Set up your Docker Compose stacks
Create override files - Add your customizations
Test with dry-run mode - Verify your configuration
Set up monitoring - Monitor the service logs

3.8 KiB Raw Blame History