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

222
Docs/configuration.md
View file

@ -1,79 +1,191 @@
# Configuration Reference
This guide covers all configuration options available in ComposeSync.
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
The service can be configured through:
ComposeSync looks for configuration files in this order:
1. `/opt/composesync/config.toml` (recommended)
2. `/opt/composesync/.env` (legacy format)
1. **Systemd Service File** (`/etc/systemd/system/composesync.service`):
- Basic service configuration
- User and group settings
- Working directory
## TOML Configuration Format (Recommended)
2. **Environment File** (`/opt/composesync/.env`):
- Base directory for stacks
- Global settings
- Stack-specific configurations
The TOML format is more readable and supports both global settings and per-stack 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
```toml
# 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"
## Global Configuration Options
# 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
```toml
[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
```toml
[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
```toml
[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:
```env
# 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)
# Global settings
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)
KEEP_VERSIONS=10
DRY_RUN=false
# Number of stacks to manage
STACKS=1
# Optional webhook URL for notifications
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
```
## Stack Configuration Options
## Migration from .env to TOML
For each stack, you can configure:
To migrate from .env to TOML:
```env
# 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)
1. **Create a new TOML file:**
```bash
sudo nano /opt/composesync/config.toml
```
# 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
2. **Convert your configuration:**
```toml
[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"
```
# 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
3. **Test the configuration:**
```bash
sudo systemctl restart composesync
sudo journalctl -u composesync -f
```
# Custom file ordering (optional, comma-separated list of numbers)
STACK_N_EXTRA_FILES_ORDER=2,1,3
```
4. **Remove the old .env file:**
```bash
sudo rm /opt/composesync/.env
```
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,...).
## Configuration File Location
## Update Modes
The configuration files are located at:
- **TOML:** `/opt/composesync/config.toml`
- **ENV:** `/opt/composesync/.env`
- **`notify_only`
Both files can be edited with any text editor:
```bash
sudo nano /opt/composesync/config.toml
# or
sudo nano /opt/composesync/.env
```