ComposeSync/Docs/configuration.md

Configuration Reference

This guide covers all configuration options available in ComposeSync.

Configuration Files

The service can be configured through:

1. Systemd Service File (/etc/systemd/system/composesync.service):

   • Basic service configuration
   • User and group settings
   • Working directory

2. Environment File (/opt/composesync/.env):

   • Base directory for stacks
   • Global settings
   • Stack-specific configurations

3. Stack Directories (/opt/composesync/stacks/<stack-name>/):

   • docker-compose.yml (managed by agent)
   • docker-compose.override.yml (your customizations)
   • Versioned copies with .bak extension

Global Configuration Options

# Base directory for all stacks
COMPOSESYNC_BASE_DIR=/opt/composesync/stacks

# Number of versions to keep per stack (default: 10)
KEEP_VERSIONS=10

# Update interval in seconds (default: 3600)
UPDATE_INTERVAL_SECONDS=3600

# Update mode: notify_only or notify_and_apply (default: notify_and_apply)
UPDATE_MODE=notify_and_apply

# Enable dry-run mode (true/false, default: false)
DRY_RUN=false

# Number of stacks to manage
STACKS=1

# Optional webhook URL for notifications
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint

Stack Configuration Options

For each stack, you can configure:

# Basic stack configuration
STACK_N_NAME=stack_name                    # Required: Name of the stack
STACK_N_URL=https://example.com/compose.yml # Required: URL to download from
STACK_N_PATH=/path/to/stack                # Required: Local path for the stack
STACK_N_TOOL=wget                          # Required: Download tool (wget or git)
STACK_N_INTERVAL=86400                     # Optional: Stack-specific interval (overrides global)
STACK_N_KEEP_VERSIONS=10                   # Optional: Stack-specific version count (overrides global)

# Git-specific options (only when STACK_N_TOOL=git)
STACK_N_GIT_SUBPATH=docker/compose.yml     # Optional: Path to compose file in repo
STACK_N_GIT_REF=main                       # Optional: Branch or tag to checkout

# Multiple compose files (numbered)
STACK_N_EXTRA_FILES_1=https://example.com/file1.yml
STACK_N_EXTRA_FILES_2=https://example.com/file2.yml
# ... continue numbering as needed

# Custom file ordering (optional, comma-separated list of numbers)
STACK_N_EXTRA_FILES_ORDER=2,1,3

If STACK_N_EXTRA_FILES_ORDER is set, extra files will be processed in the specified order (e.g., 2,1,3). Otherwise, files are processed in numeric order (1,2,3,...).

Update Modes

• **notify_only