339 lines
No EOL
7.7 KiB
Markdown
339 lines
No EOL
7.7 KiB
Markdown
# 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:
|
|
|
|
```toml
|
|
# 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:
|
|
|
|
```env
|
|
# 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
|
|
```toml
|
|
[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"
|
|
```
|
|
|
|
### Tags
|
|
```toml
|
|
[stable-release]
|
|
URL = "https://github.com/user/app.git"
|
|
PATH = "/opt/composesync/stacks/stable"
|
|
TOOL = "git"
|
|
GIT_REF = "v2.1.0"
|
|
|
|
[beta-release]
|
|
URL = "https://github.com/user/app.git"
|
|
PATH = "/opt/composesync/stacks/beta"
|
|
TOOL = "git"
|
|
GIT_REF = "beta-v2.2.0"
|
|
```
|
|
|
|
### Commit Hashes
|
|
```toml
|
|
[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`:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```toml
|
|
[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:**
|
|
```bash
|
|
# 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:
|
|
|
|
```toml
|
|
[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:**
|
|
```bash
|
|
# 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
|
|
```toml
|
|
[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
|
|
```toml
|
|
# 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
|
|
```toml
|
|
[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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Check if file exists in repository
|
|
git ls-tree -r --name-only HEAD | grep docker-compose.yml
|
|
```
|
|
|
|
### Authentication Issues
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# View ComposeSync logs
|
|
sudo journalctl -u composesync -f
|
|
|
|
# Filter for Git operations
|
|
sudo journalctl -u composesync | grep "git"
|
|
```
|
|
|
|
### Check Repository Status
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
``` |