Initial commit: ComposeSync - Automated Docker Compose update agent

Docs/git-repositories.md

@@ -0,0 +1,193 @@
+# 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
+```