Initial commit: ComposeSync - Automated Docker Compose update agent

Docs/dry-run.md

@@ -0,0 +1,204 @@
+# Dry-Run Mode
+
+This guide covers how to use dry-run mode to test your ComposeSync configuration safely.
+
+## Overview
+
+Dry-run mode allows you to test your configuration without actually applying changes. This is useful for:
+- Testing new stack configurations
+- Verifying download URLs work correctly
+- Previewing what changes would be applied
+- Debugging configuration issues
+- Testing webhook notifications
+
+## Enabling Dry-Run Mode
+
+To enable dry-run mode, add this to your `.env` file:
+
+```env
+DRY_RUN=true
+```
+
+## What Dry-Run Mode Does
+
+In dry-run mode, ComposeSync will:
+- Download and process all files normally
+- Show what actions would be taken
+- Display a preview of changes (diff output)
+- Not create backups or versioned files
+- Not apply any changes to your stacks
+- Prefix all log messages with `[DRY-RUN]`
+- Send webhook notifications (if configured)
+
+## Example Dry-Run Output
+
+```
+[2024-01-15 10:30:00] [DRY-RUN] Processing stack immich
+[2024-01-15 10:30:01] [DRY-RUN] 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] [DRY-RUN] Changes detected in immich
+[2024-01-15 10:30:02] [DRY-RUN] DRY-RUN: Would apply changes to immich
+[2024-01-15 10:30:02] [DRY-RUN] DRY-RUN: Would run: docker compose -f /opt/composesync/stacks/immich/docker-compose.yml -f /opt/composesync/stacks/immich/hwaccel.ml.yml -f /opt/composesync/stacks/immich/docker-compose.override.yml up -d
+[2024-01-15 10:30:02] [DRY-RUN] DRY-RUN: Changes that would be applied:
+[2024-01-15 10:30:02] [DRY-RUN] --- compose-20240115103000.yml.bak
+[2024-01-15 10:30:02] [DRY-RUN] +++ docker-compose.yml
+[2024-01-15 10:30:02] [DRY-RUN] @@ -1,6 +1,6 @@
+[2024-01-15 10:30:02] [DRY-RUN]  version: '3.8'
+[2024-01-15 10:30:02] [DRY-RUN]  
+[2024-01-15 10:30:02] [DRY-RUN]  services:
+[2024-01-15 10:30:02] [DRY-RUN]    immich-server:
+[2024-01-15 10:30:02] [DRY-RUN] -     image: ghcr.io/immich-app/immich-server:release
+[2024-01-15 10:30:02] [DRY-RUN] +     image: ghcr.io/immich-app/immich-server:release-1.91.0
+```
+
+## Testing New Configurations
+
+### 1. Test a New Stack
+
+1. Add a new stack configuration to your `.env` file
+2. Enable dry-run mode:
+   ```env
+   DRY_RUN=true
+   ```
+3. Restart the service:
+   ```bash
+   sudo systemctl restart composesync
+   ```
+4. Check the logs to see what would happen:
+   ```bash
+   sudo journalctl -u composesync -f
+   ```
+
+### 2. Test URL Changes
+
+1. Modify a stack URL in your `.env` file
+2. Enable dry-run mode
+3. Restart the service
+4. Verify the new URL works and downloads correctly
+
+### 3. Test Multiple Compose Files
+
+1. Add extra compose files to a stack configuration
+2. Enable dry-run mode
+3. Restart the service
+4. Verify all files are downloaded and processed correctly
+
+## Disabling Dry-Run Mode
+
+To disable dry-run mode, set `DRY_RUN=false` or remove the line from your `.env` file:
+
+```env
+DRY_RUN=false
+```
+
+Then restart the service:
+```bash
+sudo systemctl restart composesync
+```
+
+## Webhook Testing
+
+Dry-run mode is particularly useful for testing webhook notifications because:
+- Webhooks are still sent in dry-run mode
+- You can verify your webhook configuration works
+- No actual changes are applied to your stacks
+- You can test different webhook services safely
+
+## Best Practices
+
+### 1. Always Test New Configurations
+
+Before adding a new stack or changing existing configurations:
+1. Enable dry-run mode
+2. Test the configuration
+3. Verify everything works as expected
+4. Disable dry-run mode when ready
+
+### 2. Use for Debugging
+
+When troubleshooting issues:
+1. Enable dry-run mode
+2. Check the logs for detailed information
+3. Verify URLs and configurations
+4. Fix any issues before disabling dry-run mode
+
+### 3. Test Webhook Integration
+
+Use dry-run mode to test webhook notifications:
+1. Configure your webhook URL
+2. Enable dry-run mode
+3. Trigger an update cycle
+4. Verify webhook notifications are received
+
+### 4. Preview Changes
+
+Use dry-run mode to preview what changes would be applied:
+1. Enable dry-run mode
+2. Let the service run a cycle
+3. Review the diff output
+4. Decide if you want to apply the changes
+
+## Troubleshooting
+
+### No Changes Detected
+
+If dry-run mode shows "No changes detected":
+- The remote file is identical to your current file
+- This is normal and expected behavior
+- No action would be taken in normal mode either
+
+### Download Failures
+
+If you see download errors in dry-run mode:
+- Check the URL is correct and accessible
+- Verify network connectivity
+- Check for authentication requirements
+- Fix the URL before disabling dry-run mode
+
+### Configuration Errors
+
+If you see configuration errors:
+- Check your `.env` file syntax
+- Verify all required fields are present
+- Check file permissions
+- Fix configuration issues before proceeding
+
+## Example Workflow
+
+Here's a typical workflow for testing a new stack:
+
+1. **Add Configuration**
+   ```env
+   STACKS=2
+   STACK_2_NAME=test-app
+   STACK_2_URL=https://example.com/docker-compose.yml
+   STACK_2_PATH=/opt/composesync/stacks/test-app
+   STACK_2_TOOL=wget
+   ```
+
+2. **Enable Dry-Run Mode**
+   ```env
+   DRY_RUN=true
+   ```
+
+3. **Restart Service**
+   ```bash
+   sudo systemctl restart composesync
+   ```
+
+4. **Check Logs**
+   ```bash
+   sudo journalctl -u composesync -f
+   ```
+
+5. **Verify Results**
+   - Check that files are downloaded
+   - Verify no errors occur
+   - Review any changes that would be applied
+
+6. **Disable Dry-Run Mode**
+   ```env
+   DRY_RUN=false
+   sudo systemctl restart composesync
+   ```
+
+This workflow ensures your configuration is correct before applying any changes to your running stacks.