355 lines
No EOL
8.4 KiB
Markdown
355 lines
No EOL
8.4 KiB
Markdown
# 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
|
|
``` |