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

## Installation Steps

1. **Clone this repository:**
   ```bash
   git clone <your-repo-url>
   cd composesync
   ```

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

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

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