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

8.4 KiB
Raw Permalink Blame History

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:

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

# 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

# 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

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

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

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

2. Restart the Service

sudo systemctl restart composesync

3. Monitor the Logs

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

{
  "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:

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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