robojerk 70486907aa 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

2025-06-25 15:15:40 -07:00

7.7 KiB

Raw Blame History

Git Repository Setup

This guide covers how to configure ComposeSync to work with Git repositories as sources for Docker Compose files.

Overview

ComposeSync can download Docker Compose files from Git repositories, allowing you to:

Track specific branches, tags, or commits
Access files in subdirectories
Maintain version control for your compose configurations
Use private repositories (with proper authentication)

TOML Configuration (Recommended)

The TOML format provides clear and readable Git repository configuration:

# Git repository configuration
[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"

[development-app]
URL = "https://github.com/user/dev-app.git"
PATH = "/opt/composesync/stacks/dev-app"
TOOL = "git"
GIT_SUBPATH = "deploy/docker-compose.yml"
GIT_REF = "develop"
INTERVAL = 1800  # Check every 30 minutes

[stable-release]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/stable"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "v2.1.0"  # Specific tag
INTERVAL = 86400  # Check daily

Legacy .env Configuration

The .env format is supported for backward compatibility:

# Git repository configuration
STACKS=3

STACK_1_NAME=my-app
STACK_1_URL=https://github.com/user/my-app.git
STACK_1_PATH=/opt/composesync/stacks/my-app
STACK_1_TOOL=git
STACK_1_GIT_SUBPATH=docker/docker-compose.yml
STACK_1_GIT_REF=main

STACK_2_NAME=development-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=deploy/docker-compose.yml
STACK_2_GIT_REF=develop
STACK_2_INTERVAL=1800

STACK_3_NAME=stable-release
STACK_3_URL=https://github.com/user/app.git
STACK_3_PATH=/opt/composesync/stacks/stable
STACK_3_TOOL=git
STACK_3_GIT_SUBPATH=docker/docker-compose.yml
STACK_3_GIT_REF=v2.1.0
STACK_3_INTERVAL=86400

Git Configuration Options

Required Options

Option	Description	Example
`URL`	Git repository URL	`https://github.com/user/repo.git`
`PATH`	Local path for the stack	`/opt/composesync/stacks/my-app`
`TOOL`	Must be set to `"git"`	`git`

Optional Options

Option	Description	Default	Example
`GIT_SUBPATH`	Path to docker-compose.yml in repo	`docker-compose.yml` (root)	`docker/compose.yml`
`GIT_REF`	Branch, tag, or commit hash	`main`	`develop`, `v1.2.3`, `abc123`
`INTERVAL`	Update interval (seconds)	Global setting	`1800`
`KEEP_VERSIONS`	Number of backup versions	Global setting	`5`

Git Reference Types

Branches

[main-branch]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/main"
TOOL = "git"
GIT_REF = "main"

[feature-branch]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/feature"
TOOL = "git"
GIT_REF = "feature/new-ui"

Commit Hashes

[specific-commit]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/commit"
TOOL = "git"
GIT_REF = "abc123def456789"

Subdirectory Configuration

If your Docker Compose file is not in the repository root, use GIT_SUBPATH:

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

Common subdirectory patterns:

docker/docker-compose.yml
deploy/docker-compose.yml
compose/docker-compose.yml
infrastructure/docker-compose.yml

Multiple Compose Files with Git

For repositories with multiple compose files:

[complex-app]
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"

Private Repositories

SSH Authentication

For private repositories using SSH:

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

Setup SSH keys:

# Generate SSH key (if not exists)
ssh-keygen -t ed25519 -C "composesync@your-server"

# Add to SSH agent
ssh-add ~/.ssh/id_ed25519

# Add public key to GitHub/GitLab
cat ~/.ssh/id_ed25519.pub

HTTPS with Personal Access Token

For private repositories using HTTPS:

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

Setup credentials:

# Configure Git credentials
git config --global credential.helper store
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

# Test access
git clone https://github.com/user/private-app.git /tmp/test

Best Practices

1. Use Semantic Versioning

[production]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/production"
TOOL = "git"
GIT_REF = "v2.1.0"  # Specific version

[development]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/development"
TOOL = "git"
GIT_REF = "develop"  # Latest development

2. Organize by Environment

# Production environments
[prod-app]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/prod"
TOOL = "git"
GIT_REF = "main"
INTERVAL = 7200

# Development environments
[dev-app]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/dev"
TOOL = "git"
GIT_REF = "develop"
INTERVAL = 1800

3. Use Descriptive Branch Names

[stable]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/stable"
TOOL = "git"
GIT_REF = "stable"

[experimental]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/experimental"
TOOL = "git"
GIT_REF = "experimental"

Troubleshooting

Repository Not Found

# Test repository access
git clone https://github.com/user/repo.git /tmp/test

# Check SSH access
ssh -T git@github.com

Branch/Tag Not Found

# List available branches
git ls-remote --heads https://github.com/user/repo.git

# List available tags
git ls-remote --tags https://github.com/user/repo.git

Subpath Not Found

# Check if file exists in repository
git ls-tree -r --name-only HEAD | grep docker-compose.yml

Authentication Issues

# Test SSH connection
ssh -T git@github.com

# Test HTTPS with token
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

Monitoring Git Operations

View Git Operations in Logs

# View ComposeSync logs
sudo journalctl -u composesync -f

# Filter for Git operations
sudo journalctl -u composesync | grep "git"

Check Repository Status

# Check if repository is cloned
ls -la /opt/composesync/stacks/my-app/.git

# Check current branch/commit
git -C /opt/composesync/stacks/my-app/.git rev-parse --abbrev-ref HEAD
git -C /opt/composesync/stacks/my-app/.git rev-parse HEAD

Manual Git Operations

# Manually fetch updates
cd /opt/composesync/stacks/my-app/.git
git fetch origin

# Check available branches
git branch -r

# Switch to different branch
git checkout develop

7.7 KiB Raw Blame History