204 lines
No EOL
5.5 KiB
Markdown
204 lines
No EOL
5.5 KiB
Markdown
# 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. |