193 lines
No EOL
4.4 KiB
Markdown
193 lines
No EOL
4.4 KiB
Markdown
# Git Repository Setup
|
|
|
|
This guide covers how to use Git repositories as sources for your Docker Compose files.
|
|
|
|
## Basic Git Configuration
|
|
|
|
To use a Git repository as your source, set the tool to `git` and provide the repository URL:
|
|
|
|
```env
|
|
STACK_1_NAME=myapp
|
|
STACK_1_URL=https://github.com/org/repo.git
|
|
STACK_1_PATH=/opt/composesync/stacks/myapp
|
|
STACK_1_TOOL=git
|
|
```
|
|
|
|
## Git-Specific Options
|
|
|
|
### Subpath Configuration
|
|
|
|
If your `docker-compose.yml` file is not in the root of the repository, specify the subpath:
|
|
|
|
```env
|
|
STACK_1_GIT_SUBPATH=docker/docker-compose.yml
|
|
```
|
|
|
|
This is useful for repositories that organize their Docker Compose files in subdirectories.
|
|
|
|
### Branch and Tag Support
|
|
|
|
You can specify a specific branch or tag to checkout:
|
|
|
|
```env
|
|
STACK_1_GIT_REF=main
|
|
```
|
|
|
|
Examples:
|
|
- `STACK_1_GIT_REF=main` - Use the main branch
|
|
- `STACK_1_GIT_REF=v1.0.0` - Use a specific tag
|
|
- `STACK_1_GIT_REF=develop` - Use a development branch
|
|
|
|
## Complete Example
|
|
|
|
Here's a complete example of configuring a Git repository:
|
|
|
|
```env
|
|
STACK_1_NAME=portainer
|
|
STACK_1_URL=https://github.com/portainer/portainer-compose.git
|
|
STACK_1_PATH=/opt/composesync/stacks/portainer
|
|
STACK_1_TOOL=git
|
|
STACK_1_GIT_SUBPATH=docker-compose.yml
|
|
STACK_1_GIT_REF=main
|
|
STACK_1_INTERVAL=43200
|
|
STACK_1_KEEP_VERSIONS=5
|
|
```
|
|
|
|
## How Git Sources Work
|
|
|
|
When using Git as a source, ComposeSync:
|
|
|
|
1. **Clones the repository** (if not already present)
|
|
2. **Fetches updates** from the remote repository
|
|
3. **Checks out the specified branch/tag** (if configured)
|
|
4. **Extracts the compose file** from the specified subpath (or root)
|
|
5. **Uses Git commit hash** as the version identifier
|
|
|
|
## Version Identifiers
|
|
|
|
For Git sources, ComposeSync uses the Git commit hash as the version identifier:
|
|
|
|
```
|
|
compose-a1b2c3d.yml.bak # Git commit hash
|
|
```
|
|
|
|
This provides precise version tracking and makes it easy to identify which commit a version came from.
|
|
|
|
## Repository Management
|
|
|
|
### Local Repository Storage
|
|
|
|
Git repositories are stored locally in `.git` directories:
|
|
|
|
```
|
|
/opt/composesync/stacks/myapp/
|
|
├── docker-compose.yml
|
|
├── docker-compose.override.yml
|
|
├── compose-a1b2c3d.yml.bak
|
|
└── myapp.git/ # Git repository
|
|
```
|
|
|
|
### Repository Updates
|
|
|
|
ComposeSync automatically:
|
|
- Clones new repositories when first encountered
|
|
- Fetches updates from existing repositories
|
|
- Handles branch/tag changes
|
|
- Maintains local repository state
|
|
|
|
## Best Practices
|
|
|
|
### 1. Use Specific Branches/Tags
|
|
|
|
For production environments, pin to specific branches or tags for stability:
|
|
|
|
```env
|
|
STACK_1_GIT_REF=v2.1.0 # Pin to specific version
|
|
```
|
|
|
|
### 2. Use Subpaths for Organization
|
|
|
|
Organize your repositories with subpaths for better structure:
|
|
|
|
```
|
|
repository/
|
|
├── docker/
|
|
│ ├── docker-compose.yml
|
|
│ └── docker-compose.prod.yml
|
|
├── docs/
|
|
└── README.md
|
|
```
|
|
|
|
### 3. Monitor Repository Changes
|
|
|
|
Use webhook notifications to monitor when repositories are updated:
|
|
|
|
```env
|
|
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint
|
|
```
|
|
|
|
### 4. Test with Dry-Run Mode
|
|
|
|
Always test new Git configurations with dry-run mode:
|
|
|
|
```env
|
|
DRY_RUN=true
|
|
```
|
|
|
|
## Troubleshooting Git Issues
|
|
|
|
### Repository Not Found
|
|
|
|
If you get "Failed to clone" errors:
|
|
- Verify the repository URL is correct
|
|
- Ensure the repository is public or you have access
|
|
- Check network connectivity
|
|
|
|
### Subpath Not Found
|
|
|
|
If you get "Subpath not found" errors:
|
|
- Verify the subpath exists in the repository
|
|
- Check the branch/tag contains the file
|
|
- Use the correct path separator (forward slashes)
|
|
|
|
### Branch/Tag Issues
|
|
|
|
If you get "Failed to checkout" errors:
|
|
- Verify the branch/tag exists
|
|
- Check for typos in the reference name
|
|
- Ensure the reference is accessible
|
|
|
|
## Example Configurations
|
|
|
|
### Simple Repository (Root Compose File)
|
|
|
|
```env
|
|
STACK_1_NAME=simple-app
|
|
STACK_1_URL=https://github.com/user/simple-app.git
|
|
STACK_1_PATH=/opt/composesync/stacks/simple-app
|
|
STACK_1_TOOL=git
|
|
STACK_1_GIT_REF=main
|
|
```
|
|
|
|
### Complex Repository (Subpath + Tag)
|
|
|
|
```env
|
|
STACK_1_NAME=complex-app
|
|
STACK_1_URL=https://github.com/org/complex-app.git
|
|
STACK_1_PATH=/opt/composesync/stacks/complex-app
|
|
STACK_1_TOOL=git
|
|
STACK_1_GIT_SUBPATH=docker/compose/production.yml
|
|
STACK_1_GIT_REF=v1.2.3
|
|
```
|
|
|
|
### Development Branch
|
|
|
|
```env
|
|
STACK_1_NAME=dev-app
|
|
STACK_1_URL=https://github.com/user/dev-app.git
|
|
STACK_1_PATH=/opt/composesync/stacks/dev-app
|
|
STACK_1_TOOL=git
|
|
STACK_1_GIT_SUBPATH=docker/docker-compose.yml
|
|
STACK_1_GIT_REF=develop
|
|
STACK_1_INTERVAL=1800 # Check every 30 minutes for dev
|
|
``` |