robojerk/ComposeSync
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ComposeSync/Docs/troubleshooting.md

7 KiB
Raw Blame History

Troubleshooting Guide

This guide covers common issues and their solutions when using ComposeSync.

Service Issues

Service Won't Start

Problem: The ComposeSync service fails to start.

Solutions:

  1. Check service status:

    sudo systemctl status composesync

  2. Check logs for errors:

    sudo journalctl -u composesync -n 50

  3. Verify user permissions:

    # Ensure the service user is in the docker group
groups YOUR_USERNAME

  4. Check file permissions:

    # Ensure the service user owns the ComposeSync directory
ls -la /opt/composesync/
sudo chown -R YOUR_USERNAME:docker /opt/composesync/

Service Crashes or Stops Unexpectedly

Problem: The service runs but crashes or stops unexpectedly.

Solutions:

  1. Check for configuration errors:

    sudo journalctl -u composesync -f

  2. Verify your .env file syntax:

    # Check for syntax errors
source /opt/composesync/.env

  3. Test with dry-run mode:

    DRY_RUN=true

Download Issues

Failed Downloads

Problem: ComposeSync fails to download compose files.

Solutions:

  1. Check network connectivity:

    # Test if the URL is accessible
wget -q --spider https://your-url.com/docker-compose.yml
echo $?

  2. Verify URLs in your configuration:

    # Check your .env file
grep STACK_.*_URL /opt/composesync/.env

  3. Check for authentication requirements:

    • Some URLs may require authentication
    • Consider using Git repositories instead

Git Repository Issues

Problem: Git operations fail.

Solutions:

  1. Verify repository access:

    # Test git clone manually
git clone --quiet https://github.com/user/repo.git /tmp/test

  2. Check Git subpath configuration:

    # Ensure the subpath exists in the repository
git ls-tree -r --name-only HEAD | grep docker-compose.yml

  3. Verify branch/tag exists:

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

Docker Compose Issues

Update Failures

Problem: Docker Compose updates fail and trigger rollback.

Solutions:

  1. Check Docker Compose syntax:

    # Validate compose file manually
docker compose -f /path/to/docker-compose.yml config

  2. Check for port conflicts:

    # Check what's using the ports
netstat -tulpn | grep :80

  3. Verify override file syntax:

    # Test with override file
docker compose -f docker-compose.yml -f docker-compose.override.yml config

Rollback Failures

Problem: Both the update and rollback fail.

Solutions:

  1. Check backup files:

    # Verify backups exist
ls -la /opt/composesync/stacks/*/backups/

  2. Manual rollback:

    # Manually restore from backup
cp /opt/composesync/stacks/stackname/backups/backup-*/docker-compose.yml /opt/composesync/stacks/stackname/

  3. Check Docker daemon:

    # Ensure Docker is running
sudo systemctl status docker

Configuration Issues

Missing Environment Variables

Problem: Required configuration is missing.

Solutions:

  1. Check your .env file:

    # Verify all required variables are set
grep -E "STACK_.*_(NAME|URL|PATH|TOOL)" /opt/composesync/.env

  2. Check variable syntax:

    # Look for syntax errors
cat -n /opt/composesync/.env

Invalid Paths

Problem: Stack paths don't exist or are inaccessible.

Solutions:

  1. Create missing directories:

    # Create stack directories
sudo mkdir -p /opt/composesync/stacks/stackname
sudo chown YOUR_USERNAME:docker /opt/composesync/stacks/stackname

  2. Check permissions:

    # Verify directory permissions
ls -la /opt/composesync/stacks/

Webhook Issues

Webhook Notifications Not Sent

Problem: Webhook notifications aren't being sent.

Solutions:

  1. Check webhook URL:

    # Verify URL is set
grep NOTIFICATION_WEBHOOK_URL /opt/composesync/.env

  2. Test webhook manually:

    # Test webhook endpoint
curl -X POST -H "Content-Type: application/json" \
  -d '{"test": "message"}' \
  https://your-webhook-url.com/endpoint

  3. Check network connectivity:

    # Test if webhook URL is accessible
wget -q --spider https://your-webhook-url.com/endpoint

Performance Issues

High Resource Usage

Problem: ComposeSync uses too much CPU or memory.

Solutions:

  1. Increase update intervals:

    UPDATE_INTERVAL_SECONDS=7200  # Check every 2 hours instead of 1

  2. Reduce version history:

    KEEP_VERSIONS=5  # Keep fewer versions

  3. Use dry-run mode for testing:

    DRY_RUN=true

Slow Downloads

Problem: Downloads are taking too long.

Solutions:

  1. Check network connectivity:

    # Test download speed
wget -O /dev/null https://your-url.com/docker-compose.yml

  2. Consider using Git instead of wget:

    STACK_1_TOOL=git

Lock File Issues

Stale Lock Files

Problem: Lock files prevent updates.

Solutions:

  1. Check for stale locks:

    # Look for lock files
find /opt/composesync/stacks/ -name ".lock" -type d

  2. Remove stale locks manually:

    # Remove lock file (be careful!)
rm -rf /opt/composesync/stacks/stackname/.lock

  3. Restart the service:

    sudo systemctl restart composesync

Debugging Tips

Enable Verbose Logging

For detailed debugging, you can temporarily modify the log function:

# Edit the update-agent.sh file
sudo nano /opt/composesync/update-agent.sh

# Add more verbose logging
log() {
    local prefix=""
    if [ "$DRY_RUN" = "true" ]; then
        prefix="[DRY-RUN] "
    fi
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ${prefix}$1" | tee -a /tmp/composesync-debug.log
}

Test Individual Components

  1. Test download function:

    # Test wget download
wget -q -O /tmp/test.yml https://your-url.com/docker-compose.yml

  2. Test Docker Compose:

    # Test compose file manually
docker compose -f /path/to/docker-compose.yml config

  3. Test webhook:

    # Test webhook manually
curl -X POST -H "Content-Type: application/json" \
  -d '{"event": "test"}' \
  $NOTIFICATION_WEBHOOK_URL

Getting Help

If you're still experiencing issues:

  1. Check the logs:

    sudo journalctl -u composesync -f

  2. Enable dry-run mode to test without making changes:

    DRY_RUN=true

  3. Verify your configuration step by step

  4. Check the documentation for your specific use case

  5. Submit an issue with:

    • Your configuration (with sensitive data removed)
    • Relevant log output
    • Steps to reproduce the issue
    • Expected vs actual behavior