# Dry-Run Mode

Dry-run mode allows you to test ComposeSync configurations without making any actual changes to your Docker stacks. This is perfect for validating your setup before going live.

## Overview

When dry-run mode is enabled, ComposeSync will:
- Download and parse configuration files
- Show what changes would be applied
- Log all actions that would be taken
- Send webhook notifications (if configured)
- **Not** actually apply any changes to your stacks

## TOML Configuration

### Global Dry-Run Mode

Enable dry-run mode for all stacks in your TOML configuration:

```toml
# Global settings
[global]
UPDATE_INTERVAL_SECONDS = 3600
KEEP_VERSIONS = 10
DRY_RUN = true  # Enable dry-run mode for all stacks
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"

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

### Per-Stack Dry-Run Mode

Enable dry-run mode for specific stacks only:

```toml
# Global settings
[global]
UPDATE_INTERVAL_SECONDS = 3600
KEEP_VERSIONS = 10
DRY_RUN = false  # Default: apply changes

# Production stack (apply changes)
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"

# Development stack (dry-run only)
[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"
DRY_RUN = true  # Override global setting for this stack
```

## Legacy .env Configuration

### Global Dry-Run Mode

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

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

### Per-Stack Dry-Run Mode

```env
# Global settings
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10
DRY_RUN=false

# Stack configurations
STACKS=2

# Production stack (apply changes)
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

# Development stack (dry-run only)
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
STACK_2_DRY_RUN=true
```

## Testing Your Configuration

### 1. Enable Dry-Run Mode

Edit your configuration file:

```bash
# For TOML configuration
sudo nano /opt/composesync/config.toml

# For .env configuration
sudo nano /opt/composesync/.env
```

### 2. Restart the Service

```bash
sudo systemctl restart composesync
```

### 3. Monitor the Logs

```bash
# View real-time logs
sudo journalctl -u composesync -f

# View recent logs
sudo journalctl -u composesync -n 50
```

## Dry-Run Output Examples

### Successful Update (Dry-Run)

```
[2024-01-15 10:30:00] Loading TOML configuration from /opt/composesync/config.toml
[2024-01-15 10:30:00] Processing stack: immich
[2024-01-15 10:30:01] Downloading https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml to /opt/composesync/stacks/immich/docker-compose.yml
[2024-01-15 10:30:02] Changes detected for immich
[2024-01-15 10:30:02] DRY-RUN: Would apply changes to immich
[2024-01-15 10:30:02] DRY-RUN: Would run: docker compose -f /opt/composesync/stacks/immich/docker-compose.yml -f /opt/composesync/stacks/immich/docker-compose.override.yml up -d
[2024-01-15 10:30:02] DRY-RUN: Changes that would be applied:
[2024-01-15 10:30:02] --- a/docker-compose.yml
[2024-01-15 10:30:02] +++ b/docker-compose.yml
[2024-01-15 10:30:02] @@ -15,7 +15,7 @@ services:
[2024-01-15 10:30:02]    immich-server:
[2024-01-15 10:30:02] -    image: ghcr.io/immich-app/immich-server:release
[2024-01-15 10:30:02] +    image: ghcr.io/immich-app/immich-server:v1.75.0
[2024-01-15 10:30:02]      environment:
[2024-01-15 10:30:02]        - NODE_ENV=production
[2024-01-15 10:30:02] [DRY-RUN] Would send webhook notification for immich
```

### No Changes Detected (Dry-Run)

```
[2024-01-15 10:30:00] Processing stack: portainer
[2024-01-15 10:30:01] Downloading https://github.com/portainer/portainer-compose.git to /opt/composesync/stacks/portainer/docker-compose.yml
[2024-01-15 10:30:02] No changes detected for portainer
```

### Error Handling (Dry-Run)

```
[2024-01-15 10:30:00] Processing stack: dev-app
[2024-01-15 10:30:01] ERROR: Failed to download https://invalid-url.com/docker-compose.yml
[2024-01-15 10:30:01] Skipping stack dev-app due to download failure
```

## Webhook Notifications in Dry-Run Mode

When dry-run mode is enabled, webhook notifications will still be sent with a `[DRY-RUN]` prefix:

```json
{
  "event": "update_success",
  "stack_name": "immich",
  "timestamp": "2024-01-15T10:30:02Z",
  "message": "[DRY-RUN] Would apply changes to immich",
  "version_id": "20240115103002",
  "diff": "--- a/docker-compose.yml\n+++ b/docker-compose.yml\n@@ -15,7 +15,7 @@ services:\n   immich-server:\n-    image: ghcr.io/immich-app/immich-server:release\n+    image: ghcr.io/immich-app/immich-server:v1.75.0\n"
}
```

## Use Cases

### 1. Testing New Configurations

Before adding a new stack to production:

```toml
[new-stack]
URL = "https://github.com/user/new-app.git"
PATH = "/opt/composesync/stacks/new-app"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
DRY_RUN = true  # Test first
```

### 2. Validating Updates

Test updates before applying them:

```toml
[global]
DRY_RUN = true  # Test all updates

[production-stack]
URL = "https://..."
PATH = "/opt/composesync/stacks/production"
TOOL = "wget"
```

### 3. Development Environment

Keep development stacks in dry-run mode:

```toml
[development]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/dev"
TOOL = "git"
GIT_REF = "develop"
DRY_RUN = true  # Don't auto-update dev environment
```

### 4. Configuration Validation

Validate your configuration without affecting running services:

```bash
# Enable dry-run mode
sudo nano /opt/composesync/config.toml

# Restart service
sudo systemctl restart composesync

# Check logs for any configuration errors
sudo journalctl -u composesync -f
```

## Best Practices

### 1. Always Test First

```toml
# Test configuration before going live
[global]
DRY_RUN = true

[my-stack]
URL = "https://..."
PATH = "/opt/composesync/stacks/my-stack"
TOOL = "wget"
```

### 2. Use Per-Stack Control

```toml
# Production stacks (apply changes)
[production]
URL = "https://..."
PATH = "/opt/composesync/stacks/production"
TOOL = "wget"

# Development stacks (dry-run only)
[development]
URL = "https://..."
PATH = "/opt/composesync/stacks/development"
TOOL = "git"
DRY_RUN = true
```

### 3. Monitor Webhook Notifications

Even in dry-run mode, webhook notifications help you:
- Verify your webhook configuration
- See what changes would be applied
- Monitor the update process

### 4. Gradual Rollout

```toml
# Phase 1: Test with dry-run
[global]
DRY_RUN = true

# Phase 2: Enable for specific stacks
[stable-stack]
URL = "https://..."
PATH = "/opt/composesync/stacks/stable"
TOOL = "wget"
DRY_RUN = false  # Override global setting

# Phase 3: Enable for all stacks
[global]
DRY_RUN = false
```

## Troubleshooting

### Dry-Run Not Working

```bash
# Check if dry-run is enabled
grep -i "dry_run" /opt/composesync/config.toml

# Check service logs
sudo journalctl -u composesync -n 20

# Verify configuration syntax
sudo systemctl status composesync
```

### Unexpected Behavior

```bash
# Check for conflicting settings
grep -A 5 -B 5 "DRY_RUN" /opt/composesync/config.toml

# View detailed logs
sudo journalctl -u composesync -f
```

### Webhook Issues

```bash
# Test webhook manually
curl -X POST -H "Content-Type: application/json" \
  -d '{"event": "test", "message": "[DRY-RUN] Test notification"}' \
  https://your-webhook-url.com/endpoint
```