ComposeSync/Docs/configuration.md

Configuration Reference

ComposeSync supports two configuration formats: TOML (recommended) and .env (legacy). The TOML format is more readable and easier to manage for multiple stacks.

Configuration Files

ComposeSync looks for configuration files in this order:

1. /opt/composesync/config.toml (recommended)
2. /opt/composesync/.env (legacy format)

TOML Configuration Format (Recommended)

The TOML format is more readable and supports both global settings and per-stack configurations:

# Global settings for all stacks
[global]
UPDATE_INTERVAL_SECONDS = 3600  # Check every hour
KEEP_VERSIONS = 10              # Keep 10 versions
DRY_RUN = false                 # Set to true for testing
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"
INTERVAL = 3600  # Check every hour

[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"
INTERVAL = 1800  # Check every 30 minutes for dev

TOML Format Benefits

• More readable - Clear section-based organization
• Better comments - Full comment support
• No numbering - Stack names are used directly
• Type safety - Better handling of values
• Easier maintenance - Add/remove stacks without renumbering

TOML Configuration Options

Global Settings

Option	Description	Default	Example
UPDATE_INTERVAL_SECONDS	How often to check for updates (seconds)	3600	1800
KEEP_VERSIONS	Number of backup versions to keep	10	5
DRY_RUN	Test mode (don't apply changes)	false	true
NOTIFICATION_WEBHOOK_URL	Webhook URL for notifications	""	https://...

Per-Stack Settings

Option	Description	Required	Example
URL	Source URL for docker-compose.yml	Yes	https://...
PATH	Local path for the stack	Yes	/opt/composesync/stacks/name
TOOL	Download tool (wget or git)	Yes	git
INTERVAL	Update interval for this stack (overrides global)	No	1800
KEEP_VERSIONS	Backup versions for this stack (overrides global)	No	5

Git-Specific Options

Option	Description	Required	Example
GIT_SUBPATH	Path to docker-compose.yml in repository	No	docker/
GIT_REF	Git branch, tag, or commit hash to checkout	No	main, v1.2.3, abc1234
COMPOSE_FILENAME	Custom compose file name for Git repositories	No	main.yml, docker-compose.prod.yml

Multiple Compose Files

Option	Description	Required	Example
EXTRA_FILES_1	Additional compose file URL (wget only)	No	https://example.com/network.yml
EXTRA_FILES_2	Additional compose file URL (wget only)	No	https://example.com/volumes.yml
EXTRA_FILES_ORDER	Custom order for extra files	No	2,1,3

TOML Examples

Simple Stack

[immich]
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
PATH = "/opt/composesync/stacks/immich"
TOOL = "wget"

Git Repository with Subpath

[my-app]
URL = "https://github.com/user/my-app.git"
PATH = "/opt/composesync/stacks/my-app"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"

Complex Stack with Multiple Files

[complex-stack]
URL = "https://github.com/user/complex-app.git"
PATH = "/opt/composesync/stacks/complex"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
EXTRA_FILES_1 = "https://raw.githubusercontent.com/user/complex-app/main/docker/network.yml"
EXTRA_FILES_2 = "https://raw.githubusercontent.com/user/complex-app/main/docker/volumes.yml"
EXTRA_FILES_ORDER = "1,2"

Legacy .env Configuration Format

The .env format uses numbered environment variables and is supported for backward compatibility:

# Global settings
UPDATE_INTERVAL_SECONDS=3600
KEEP_VERSIONS=10
DRY_RUN=false
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint

# Number of stacks
STACKS=2

# Stack 1
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
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

Migration from .env to TOML

To migrate from .env to TOML:

1. Create a new TOML file:

   sudo nano /opt/composesync/config.toml
   

2. Convert your configuration:

   [global]
   UPDATE_INTERVAL_SECONDS = 3600
   KEEP_VERSIONS = 10
   DRY_RUN = false
   
   [your-stack-name]
   URL = "your-url"
   PATH = "/opt/composesync/stacks/your-stack"
   TOOL = "wget"
   

3. Test the configuration:

   sudo systemctl restart composesync
   sudo journalctl -u composesync -f
   

4. Remove the old .env file:

   sudo rm /opt/composesync/.env
   

Configuration File Location

The configuration files are located at:

• TOML: /opt/composesync/config.toml
• ENV: /opt/composesync/.env

Both files can be edited with any text editor:

sudo nano /opt/composesync/config.toml
# or
sudo nano /opt/composesync/.env