ComposeSync/Docs/installation.md

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

• Linux system with systemd
• Docker and Docker Compose installed
• User with sudo privileges
• Git and wget (for downloading compose files)

Installation Steps

1. Download and Install

# Clone or download ComposeSync
git clone https://github.com/your-repo/ComposeSync.git
cd ComposeSync

# Run the installation script
sudo ./install.sh

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:

sudo nano /opt/composesync/config.toml

Example configuration:

# 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:

sudo nano /opt/composesync/.env

Example configuration:

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:

# 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:

sudo nano /opt/composesync/stacks/immich/docker-compose.override.yml

Example override:

version: '3.8'
services:
  immich-server:
    environment:
      - DATABASE_URL=postgresql://user:pass@localhost:5432/immich
    volumes:
      - /path/to/photos:/photos

5. Start the Service

# 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:

# 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

• Configuration Reference - All configuration options
• Multi-Stack Setup - Managing multiple stacks
• Safety Features - Rollback and error handling
• Monitoring - Logs and service management