robojerk/ComposeSync
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ComposeSync/Docs/dry-run.md

5.5 KiB
Raw Blame History

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:

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: 
    DRY_RUN=true
  3. Restart the service: 
    sudo systemctl restart composesync
  4. Check the logs to see what would happen: 
    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:

DRY_RUN=false

Then restart the service:

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

    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

    DRY_RUN=true

  3. Restart Service

    sudo systemctl restart composesync

  4. Check Logs

    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

    DRY_RUN=false
sudo systemctl restart composesync

This workflow ensures your configuration is correct before applying any changes to your running stacks.