Initial commit: ComposeSync - Automated Docker Compose update agent

Docs/installation.md

@@ -0,0 +1,132 @@
+# Installation Guide
+
+This guide covers the complete installation process for ComposeSync.
+
+## Deployment Model
+
+ComposeSync is designed to run **directly on the host system** as a systemd service, not in a container. This provides:
+- Direct access to the Docker daemon via `/var/run/docker.sock`
+- Better performance and reliability
+- Standard systemd service management
+- Native file system access for backups and versioning
+
+## Security Considerations
+
+Since ComposeSync runs with Docker group privileges, ensure:
+- Only trusted users have access to the ComposeSync configuration
+- The service user is properly restricted
+- Regular security updates are applied
+- Monitor logs for any suspicious activity
+
+## Prerequisites
+
+Make sure these are installed on your host system:
+
+* **Docker Engine** and **Docker Compose Plugin** (ensure `docker` and `docker compose` commands work)
+* **Basic Utilities:** `wget`, `git`, `bash`, `curl`, `diffutils`
+  ```bash
+  # On Debian/Ubuntu:
+  sudo apt install wget git bash curl diffutils
+  ```
+* **User in Docker Group:** The user you specify during installation must be in the `docker` group
+  ```bash
+  sudo usermod -aG docker YOUR_USERNAME
+  # Then log out and back in
+  ```
+
+## Installation Steps
+
+1. **Clone this repository:**
+   ```bash
+   git clone <your-repo-url>
+   cd composesync
+   ```
+
+2. **Run the installation script as root:**
+   ```bash
+   sudo ./install.sh
+   ```
+   The script will:
+   - Ask for the username to run ComposeSync
+   - Verify the user exists and is in the docker group
+   - Create necessary directories and set permissions
+   - Set up the systemd service
+   - Create a default configuration
+
+3. **Configure your stacks in `/opt/composesync/.env`:**
+   ```bash
+   sudo nano /opt/composesync/.env
+   ```
+   Example configuration:
+   ```env
+   # Base directory for stacks
+   COMPOSESYNC_BASE_DIR=/opt/composesync/stacks
+
+   # Number of versions to keep (default: 10)
+   KEEP_VERSIONS=10
+
+   # Update interval in seconds (default: 3600)
+   UPDATE_INTERVAL_SECONDS=3600
+
+   # Update mode (notify_only or notify_and_apply)
+   UPDATE_MODE=notify_and_apply
+
+   # Stack configurations
+   STACKS=1
+
+   STACK_1_NAME=immich
+   STACK_1_URL=https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
+   STACK_1_PATH=/opt/composesync/stacks/immich
+   STACK_1_TOOL=wget
+   STACK_1_INTERVAL=86400
+   STACK_1_KEEP_VERSIONS=10
+   ```
+
+4. **Create stack directories:**
+   ```bash
+   sudo mkdir -p /opt/composesync/stacks/immich
+   sudo chown YOUR_USERNAME:docker /opt/composesync/stacks/immich
+   ```
+
+5. **Restart the service to apply changes:**
+   ```bash
+   sudo systemctl restart composesync
+   ```
+
+## How It Works
+
+ComposeSync runs as a systemd service and monitors your configured stacks for updates. When changes are detected, it:
+
+1. Creates a backup of the current configuration
+2. Downloads the new configuration
+3. Applies your custom overrides
+4. Updates the stack if in `notify_and_apply` mode
+5. Maintains versioned copies of configurations
+
+## Directory Structure
+
+```
+/opt/composesync/
+├── update-agent.sh
+├── .env
+└── stacks/
+    ├── immich/
+    │   ├── docker-compose.yml
+    │   ├── docker-compose.override.yml
+    │   ├── compose-*.yml.bak
+    │   └── backups/
+    └── portainer/
+        ├── docker-compose.yml
+        ├── docker-compose.override.yml
+        ├── compose-*.yml.bak
+        └── backups/
+```
+
+## Next Steps
+
+After installation, you should:
+
+1. **[Configure your stacks](configuration.md)** - Set up your Docker Compose stacks
+2. **[Create override files](multi-stack.md#creating-override-files)** - Add your customizations
+3. **[Test with dry-run mode](dry-run.md)** - Verify your configuration
+4. **[Set up monitoring](monitoring.md)** - Monitor the service logs