robojerk/ComposeSync
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Major improvements: flexible install dir, configurable compose file name for git, enhanced webhook notifications, cross-platform lock, robust rollback, and updated docs.\n\n- Install dir is now user-confirmable and dynamic\n- Added COMPOSE_FILENAME for git stacks\n- Webhook payloads now include git context and rollback events\n- Lock file age check is cross-platform\n- Rollback notifications for success/failure\n- Updated TOML example and documentation\n- Many robustness and UX improvements

Browse source
This commit is contained in:
robojerk 2025-06-25 15:15:40 -07:00
parent f0dba7cc0a
commit 70486907aa
18 changed files with 3788 additions and 1767 deletions
Download patch file Download diff file Expand all files Collapse all files

567
Docs/webhooks.md
View file

@ -1,222 +1,465 @@
# Webhook Notifications
This guide covers how to set up and configure webhook notifications in ComposeSync.
## Overview
ComposeSync can send webhook notifications when updates are applied or when errors occur. This is useful for:
- Monitoring update status remotely
- Integrating with notification systems (Discord, Slack, etc.)
- Alerting on failed updates
- Keeping track of when stacks are updated
ComposeSync can send webhook notifications for various events, including enhanced Git context information.
## Configuration
To enable webhook notifications, add this to your `.env` file:
Set the webhook URL in your configuration:
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://your-webhook-url.com/endpoint"
```
Or in `.env` format:
```env
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint
```
## Webhook Events
ComposeSync sends notifications for the following events:
| Event | Description | When Sent |
|-------|-------------|-----------|
| `update_success` | Stack updated successfully | After successful docker compose up |
| `update_failure` | Update failed, rollback initiated | When docker compose up fails |
| `rollback_success` | Rollback completed successfully | After successful rollback |
| `rollback_failure` | Rollback failed | When rollback also fails |
| `dry_run` | Dry-run mode simulation | When DRY_RUN=true |
## Webhook Payload
The webhook will be called with a JSON payload containing:
- `event`: The type of event (`update_success`, `update_failure`, `error`)
- `stack_name`: The name of the stack being updated
- `timestamp`: When the event occurred
- `message`: A human-readable description of what happened
- `version_id`: The version identifier for the update (if applicable)
- `diff`: A unified diff (truncated to 50 lines) showing the changes applied to the main compose file (for update_success and update_failure events; null for errors)
## Event Types
### Update Success
Sent when a stack is successfully updated. Includes a diff of the changes:
Each webhook notification includes:
```json
{
"event": "update_success",
"stack_name": "immich",
"timestamp": "2024-01-15T10:30:00Z",
"message": "Successfully updated stack immich to version a1b2c3d",
"version_id": "a1b2c3d",
"diff": "--- compose-a1b2c3d.yml.bak\n+++ docker-compose.yml\n@@ -1,6 +1,6 @@\n version: '3.8'\n services:\n immich-server:\n- image: ghcr.io/immich-app/immich-server:release\n+ image: ghcr.io/immich-app/immich-server:release-1.91.0\n... (diff truncated, showing first 50 lines)"
"message": "Successfully updated stack immich",
"version_id": "abc1234",
"diff": "- old line\n+ new line\n...",
"git_context": "Commit: abc1234 - Update dependencies (Ref: main) | Repo: immich-app"
}
```
### Update Failure
### Payload Fields
Sent when a stack update fails and rollback occurs. Includes the diff that was attempted:
| Field | Description | Example |
|-------|-------------|---------|
| `event` | Event type | `update_success` |
| `stack_name` | Name of the stack | `immich` |
| `timestamp` | ISO 8601 timestamp | `2024-01-15T10:30:00Z` |
| `message` | Human-readable message | `Successfully updated stack immich` |
| `version_id` | Version identifier | `abc1234` (Git commit) or `20240115103000` (timestamp) |
| `diff` | Changes applied (truncated to 50 lines) | `- old line\n+ new line` |
| `git_context` | Git information (for Git repositories) | `Commit: abc1234 - Update deps (Ref: main) | Repo: immich-app` |
## Git Context Information
For Git repositories, the `git_context` field provides:
- **Commit hash**: Short commit hash
- **Commit message**: First 100 characters of commit message
- **Reference**: Branch, tag, or commit hash being tracked
- **Repository**: Repository name (sanitized)
Example Git context:
```
Commit: abc1234 - Update dependencies and fix security issues (Ref: main) | Repo: immich-app
```
## Testing Webhooks
You can test webhook notifications using services like:
- [webhook.site](https://webhook.site/) - Temporary webhook endpoints
- [ngrok](https://ngrok.com/) - Expose local endpoints
- [Discord webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)
- [Slack webhooks](https://api.slack.com/messaging/webhooks)
## Example: Discord Integration
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"
```
## Example: Slack Integration
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://hooks.slack.com/services/YOUR_WEBHOOK_URL"
```
## Error Handling
- Webhook failures don't stop the update process
- Failed webhook requests are logged but don't cause errors
- Network timeouts are handled gracefully
## Overview
Webhook notifications provide:
- Real-time updates on stack changes
- Error notifications for failed updates
- Integration with monitoring systems
- Diff output showing what changed
- Support for dry-run mode notifications
## TOML Configuration
### Global Webhook Configuration
Configure webhooks for all stacks in your TOML file:
```toml
# Global settings
[global]
UPDATE_INTERVAL_SECONDS = 3600
KEEP_VERSIONS = 10
DRY_RUN = false
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 Webhook Configuration
Override webhook settings for specific stacks:
```toml
# Global settings
[global]
UPDATE_INTERVAL_SECONDS = 3600
KEEP_VERSIONS = 10
NOTIFICATION_WEBHOOK_URL = "https://default-webhook.com/endpoint"
# Production stack (use global webhook)
[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"
# Development stack (different webhook)
[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"
NOTIFICATION_WEBHOOK_URL = "https://dev-webhook.com/endpoint"
```
## Legacy .env Configuration
### Global Webhook Configuration
```env
# Global settings
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10
DRY_RUN=false
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 Webhook Configuration
```env
# Global settings
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10
NOTIFICATION_WEBHOOK_URL=https://default-webhook.com/endpoint
# Stack configurations
STACKS=2
# Production stack (use global webhook)
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 (different webhook)
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_NOTIFICATION_WEBHOOK_URL=https://dev-webhook.com/endpoint
```
## Webhook Payload Format
ComposeSync sends JSON payloads with the following structure:
```json
{
"event": "update_success",
"stack_name": "immich",
"timestamp": "2024-01-15T10:30:02Z",
"message": "Successfully updated stack 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"
}
```
### Event Types
| Event | Description | When Sent |
|-------|-------------|-----------|
| `update_success` | Stack updated successfully | After successful update |
| `update_failure` | Stack update failed | After failed update (with rollback) |
| `dry_run` | Dry-run mode notification | When dry-run mode is enabled |
### Payload Fields
| Field | Type | Description |
|-------|------|-------------|
| `event` | string | Event type (update_success, update_failure, dry_run) |
| `stack_name` | string | Name of the stack being updated |
| `timestamp` | string | ISO 8601 timestamp |
| `message` | string | Human-readable message |
| `version_id` | string | Version identifier (timestamp or git commit) |
| `diff` | string | Unified diff of changes (truncated to 50 lines) |
## Webhook Service Examples
### Discord Webhook
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_TOKEN"
```
Discord will display the notification with:
- Stack name as title
- Message as content
- Diff in a code block
- Timestamp
### Slack Webhook
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://hooks.slack.com/services/YOUR_WORKSPACE/YOUR_CHANNEL/YOUR_TOKEN"
```
Slack will display:
- Rich message with stack information
- Diff in a collapsible section
- Color coding for success/failure
### Microsoft Teams Webhook
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://your-org.webhook.office.com/webhookb2/YOUR_WEBHOOK_ID/IncomingWebhook/YOUR_TOKEN/YOUR_CHANNEL"
```
Teams will show:
- Adaptive card with stack details
- Diff in a code block
- Action buttons for quick access
### Custom Webhook Service
```toml
[global]
NOTIFICATION_WEBHOOK_URL = "https://your-service.com/webhook"
```
Your service can parse the JSON payload to:
- Store update history
- Trigger automated responses
- Send email notifications
- Update monitoring dashboards
## Dry-Run Mode Notifications
When dry-run mode is enabled, webhooks are still 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"
}
```
This is useful for:
- Testing webhook configurations
- Previewing changes before applying
- Validating webhook integrations
## Error Notifications
When updates fail, ComposeSync sends error notifications:
```json
{
"event": "update_failure",
"stack_name": "immich",
"timestamp": "2024-01-15T10:30:00Z",
"timestamp": "2024-01-15T10:30:02Z",
"message": "Failed to update stack immich, rolled back to previous version",
"version_id": "a1b2c3d",
"diff": "--- compose-a1b2c3d.yml.bak\n+++ docker-compose.yml\n@@ -1,6 +1,6 @@\n ... (diff truncated, showing first 50 lines)"
"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"
}
```
### Error
Sent when a general error occurs. The diff field is null:
```json
{
"event": "error",
"stack_name": "immich",
"timestamp": "2024-01-15T10:30:00Z",
"message": "Failed to download compose file for stack immich",
"version_id": null,
"diff": null
}
```
## Integration Examples
### Discord
1. Create a Discord webhook in your server settings
2. Configure ComposeSync with the webhook URL:
```env
NOTIFICATION_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
```
Discord will automatically format the JSON payload into a readable message.
### Slack
1. Create a Slack webhook in your workspace settings
2. Configure ComposeSync with the webhook URL:
```env
NOTIFICATION_WEBHOOK_URL=https://hooks.slack.com/services/YOUR_WEBHOOK_URL
```
Slack will display the notification in your configured channel.
### Custom Webhook Server
You can create your own webhook server to handle notifications:
```python
from flask import Flask, request
import json
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook():
data = request.json
if data['event'] == 'update_success':
print(f"✅ {data['stack_name']} updated successfully")
elif data['event'] == 'update_failure':
print(f"❌ {data['stack_name']} update failed")
elif data['event'] == 'error':
print(f"⚠️ Error with {data['stack_name']}: {data['message']}")
return 'OK', 200
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000)
```
## Dry-Run Mode
**Important:** Webhook notifications are sent regardless of whether you're in dry-run mode. This allows you to test your webhook configuration safely without applying actual changes.
## Testing Webhooks
To test your webhook configuration:
### Manual Testing
1. Enable dry-run mode:
```env
DRY_RUN=true
```
Test your webhook endpoint manually:
2. Restart the service:
```bash
sudo systemctl restart composesync
```
```bash
# Test basic webhook
curl -X POST -H "Content-Type: application/json" \
-d '{"event": "test", "message": "Test notification"}' \
https://your-webhook-url.com/endpoint
3. Check your webhook endpoint for test notifications
# Test with full payload
curl -X POST -H "Content-Type: application/json" \
-d '{
"event": "update_success",
"stack_name": "test-stack",
"timestamp": "2024-01-15T10:30:02Z",
"message": "Test update notification",
"version_id": "test-123",
"diff": "--- a/test.yml\n+++ b/test.yml\n@@ -1,1 +1,1 @@\n- old\n+ new\n"
}' \
https://your-webhook-url.com/endpoint
```
## Troubleshooting
### Enable Dry-Run Mode
### Webhook Not Sent
Test webhooks safely with dry-run mode:
If webhooks aren't being sent:
```toml
[global]
DRY_RUN = true
NOTIFICATION_WEBHOOK_URL = "https://your-webhook-url.com/endpoint"
1. Check the webhook URL is correct
2. Verify the service can reach the webhook endpoint
3. Check the service logs for webhook errors:
```bash
sudo journalctl -u composesync -f
```
### Webhook Failures
If webhook calls are failing:
1. Check the webhook endpoint is accessible
2. Verify the endpoint accepts POST requests
3. Check for authentication requirements
4. Test the webhook URL manually:
```bash
curl -X POST -H "Content-Type: application/json" \
-d '{"test": "message"}' \
https://your-webhook-url.com/endpoint
```
### Rate Limiting
Some webhook services have rate limits. If you're hitting limits:
1. Increase the update interval
2. Use a different webhook service
3. Implement your own webhook server with rate limiting
[test-stack]
URL = "https://github.com/user/test-app.git"
PATH = "/opt/composesync/stacks/test"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
```
## Best Practices
### 1. Use HTTPS
### 1. Use Different Webhooks for Different Environments
Always use HTTPS URLs for webhooks to ensure security:
```env
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint
```toml
# Production webhook
[global]
NOTIFICATION_WEBHOOK_URL = "https://prod-webhook.com/endpoint"
# Development webhook
[dev-app]
URL = "https://github.com/user/dev-app.git"
PATH = "/opt/composesync/stacks/dev-app"
TOOL = "git"
NOTIFICATION_WEBHOOK_URL = "https://dev-webhook.com/endpoint"
```
### 2. Test Your Webhook
### 2. Handle Webhook Failures Gracefully
Always test your webhook configuration with dry-run mode before going live.
ComposeSync continues to work even if webhook notifications fail:
- Webhook failures don't affect stack updates
- Failed webhooks are logged but don't stop the process
- You can monitor webhook delivery in the logs
### 3. Monitor Webhook Failures
### 3. Secure Your Webhooks
Set up monitoring for webhook failures to ensure you don't miss important notifications.
- Use HTTPS endpoints only
- Consider webhook authentication if supported
- Rotate webhook tokens regularly
- Monitor webhook access logs
### 4. Use Descriptive Messages
### 4. Monitor Webhook Delivery
The webhook messages are designed to be human-readable and informative.
```bash
# Check webhook delivery in logs
sudo journalctl -u composesync | grep "webhook"
### 5. Handle Different Event Types
# Filter for webhook errors
sudo journalctl -u composesync | grep "ERROR.*webhook"
```
Configure your webhook endpoint to handle all event types appropriately.
## Troubleshooting
## Advanced Configuration
### Webhook Not Being Sent
### Custom Webhook Headers
```bash
# Check if webhook URL is configured
grep "NOTIFICATION_WEBHOOK_URL" /opt/composesync/config.toml
If your webhook service requires custom headers, you may need to modify the webhook sending code in the update script.
# Check service logs for webhook errors
sudo journalctl -u composesync | grep "webhook"
```
### Multiple Webhooks
### Webhook Delivery Failures
To send to multiple webhook endpoints, you can modify the webhook sending function to iterate through multiple URLs.
```bash
# Test webhook endpoint manually
curl -X POST -H "Content-Type: application/json" \
-d '{"test": "message"}' \
https://your-webhook-url.com/endpoint
### Webhook Authentication
# Check network connectivity
wget -q --spider https://your-webhook-url.com/endpoint
echo $?
```
For webhooks requiring authentication, you can include credentials in the URL or modify the webhook sending code to include headers.
### Webhook Payload Issues
```bash
# Check webhook payload format
sudo journalctl -u composesync | grep "payload"
# Verify JSON syntax
echo '{"test": "payload"}' | jq .
```
### Rate Limiting
If your webhook service has rate limits:
- Consider batching notifications
- Implement retry logic in your webhook service
- Use different webhooks for different stacks