# 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

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

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

- **[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