ComposeSync/Docs/configuration.md

# Configuration Reference

ComposeSync supports two configuration formats: **TOML** (recommended) and **.env** (legacy). The TOML format is more readable and easier to manage for multiple stacks.

## Configuration Files

ComposeSync looks for configuration files in this order:
1. `/opt/composesync/config.toml` (recommended)
2. `/opt/composesync/.env` (legacy format)

## TOML Configuration Format (Recommended)

The TOML format is more readable and supports both global settings and per-stack configurations:

```toml
# Global settings for all stacks
[global]
UPDATE_INTERVAL_SECONDS = 3600  # Check every hour
KEEP_VERSIONS = 10              # Keep 10 versions
DRY_RUN = false                 # Set to true for testing
NOTIFICATION_WEBHOOK_URL = "https://your-webhook-url.com/endpoint"

# Stack configurations
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"
INTERVAL = 3600  # Check every hour

[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 for dev
```

### TOML Format Benefits

- **More readable** - Clear section-based organization
- **Better comments** - Full comment support
- **No numbering** - Stack names are used directly
- **Type safety** - Better handling of values
- **Easier maintenance** - Add/remove stacks without renumbering

### TOML Configuration Options

#### Global Settings

| Option | Description | Default | Example |
|--------|-------------|---------|---------|
| `UPDATE_INTERVAL_SECONDS` | How often to check for updates (seconds) | `3600` | `1800` |
| `KEEP_VERSIONS` | Number of backup versions to keep | `10` | `5` |
| `DRY_RUN` | Test mode (don't apply changes) | `false` | `true` |
| `NOTIFICATION_WEBHOOK_URL` | Webhook URL for notifications | `""` | `https://...` |

#### Per-Stack Settings

| Option | Description | Required | Example |
|--------|-------------|----------|---------|
| `URL` | Source URL for docker-compose.yml | Yes | `https://...` |
| `PATH` | Local path for the stack | Yes | `/opt/composesync/stacks/name` |
| `TOOL` | Download tool (`wget` or `git`) | Yes | `git` |
| `INTERVAL` | Update interval for this stack (overrides global) | No | `1800` |
| `KEEP_VERSIONS` | Backup versions for this stack (overrides global) | No | `5` |

#### Git-Specific Options

| Option | Description | Required | Example |
|--------|-------------|----------|---------|
| `GIT_SUBPATH` | Path to docker-compose.yml in repository | No | `docker/` |
| `GIT_REF` | Git branch, tag, or commit hash to checkout | No | `main`, `v1.2.3`, `abc1234` |
| `COMPOSE_FILENAME` | Custom compose file name for Git repositories | No | `main.yml`, `docker-compose.prod.yml` |

#### Multiple Compose Files

| Option | Description | Required | Example |
|--------|-------------|----------|---------|
| `EXTRA_FILES_1` | Additional compose file URL (wget only) | No | `https://example.com/network.yml` |
| `EXTRA_FILES_2` | Additional compose file URL (wget only) | No | `https://example.com/volumes.yml` |
| `EXTRA_FILES_ORDER` | Custom order for extra files | No | `2,1,3` |

### TOML Examples

#### Simple Stack
```toml
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"
```

#### Git Repository with Subpath
```toml
[my-app]
URL = "https://github.com/user/my-app.git"
PATH = "/opt/composesync/stacks/my-app"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
```

#### Complex Stack with Multiple Files
```toml
[complex-stack]
URL = "https://github.com/user/complex-app.git"
PATH = "/opt/composesync/stacks/complex"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
EXTRA_FILES_1 = "https://raw.githubusercontent.com/user/complex-app/main/docker/network.yml"
EXTRA_FILES_2 = "https://raw.githubusercontent.com/user/complex-app/main/docker/volumes.yml"
EXTRA_FILES_ORDER = "1,2"
```

## Legacy .env Configuration Format

The .env format uses numbered environment variables and is supported for backward compatibility:

```env
# Global settings
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10
DRY_RUN=false
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint

# Number of stacks
STACKS=2

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

## Migration from .env to TOML

To migrate from .env to TOML:

1. **Create a new TOML file:**
   ```bash
   sudo nano /opt/composesync/config.toml
   ```

2. **Convert your configuration:**
   ```toml
   [global]
   UPDATE_INTERVAL_SECONDS = 3600
   KEEP_VERSIONS = 10
   DRY_RUN = false
   
   [your-stack-name]
   URL = "your-url"
   PATH = "/opt/composesync/stacks/your-stack"
   TOOL = "wget"
   ```

3. **Test the configuration:**
   ```bash
   sudo systemctl restart composesync
   sudo journalctl -u composesync -f
   ```

4. **Remove the old .env file:**
   ```bash
   sudo rm /opt/composesync/.env
   ```

## Configuration File Location

The configuration files are located at:
- **TOML:** `/opt/composesync/config.toml`
- **ENV:** `/opt/composesync/.env`

Both files can be edited with any text editor:

```bash
sudo nano /opt/composesync/config.toml
# or
sudo nano /opt/composesync/.env
```