183 lines
No EOL
4.2 KiB
Markdown
183 lines
No EOL
4.2 KiB
Markdown
# 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
|
|
|
|
- Linux system with systemd
|
|
- Docker and Docker Compose installed
|
|
- User with sudo privileges
|
|
- Git and wget (for downloading compose files)
|
|
|
|
## Installation Steps
|
|
|
|
### 1. Download and Install
|
|
|
|
```bash
|
|
# Clone or download ComposeSync
|
|
git clone https://github.com/your-repo/ComposeSync.git
|
|
cd ComposeSync
|
|
|
|
# Run the installation script
|
|
sudo ./install.sh
|
|
```
|
|
|
|
The installation script will:
|
|
- Create the `/opt/composesync` directory
|
|
- Copy scripts and configuration files
|
|
- Create a systemd service
|
|
- Set up proper permissions
|
|
|
|
### 2. Configure Your Stacks
|
|
|
|
#### TOML Configuration (Recommended)
|
|
|
|
Create your configuration file:
|
|
|
|
```bash
|
|
sudo nano /opt/composesync/config.toml
|
|
```
|
|
|
|
Example configuration:
|
|
|
|
```toml
|
|
# Global settings
|
|
[global]
|
|
UPDATE_INTERVAL_SECONDS = 3600 # Check every hour
|
|
KEEP_VERSIONS = 10
|
|
DRY_RUN = false
|
|
|
|
# Stack configurations
|
|
[immich]
|
|
URL = "https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"
|
|
PATH = "/opt/composesync/stacks/immich"
|
|
TOOL = "wget"
|
|
|
|
[dev-app]
|
|
URL = "https://github.com/user/dev-app.git"
|
|
PATH = "/opt/composesync/stacks/dev-app"
|
|
TOOL = "git"
|
|
GIT_SUBPATH = "docker/docker-compose.yml"
|
|
GIT_REF = "develop"
|
|
INTERVAL = 1800 # Check every 30 minutes
|
|
```
|
|
|
|
#### Legacy .env Configuration
|
|
|
|
If you prefer the legacy .env format:
|
|
|
|
```bash
|
|
sudo nano /opt/composesync/.env
|
|
```
|
|
|
|
Example configuration:
|
|
|
|
```env
|
|
UPDATE_INTERVAL_SECONDS=3600
|
|
KEEP_VERSIONS=10
|
|
DRY_RUN=false
|
|
STACKS=2
|
|
|
|
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_2_NAME=dev-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=docker/docker-compose.yml
|
|
STACK_2_GIT_REF=develop
|
|
```
|
|
|
|
### 3. Create Stack Directories
|
|
|
|
Create directories for your stacks:
|
|
|
|
```bash
|
|
# For each stack in your configuration
|
|
sudo mkdir -p /opt/composesync/stacks/immich
|
|
sudo mkdir -p /opt/composesync/stacks/dev-app
|
|
|
|
# Set proper ownership
|
|
sudo chown -R $USER:docker /opt/composesync/stacks/
|
|
```
|
|
|
|
### 4. Create Override Files (Optional)
|
|
|
|
Create `docker-compose.override.yml` files for your customizations:
|
|
|
|
```bash
|
|
sudo nano /opt/composesync/stacks/immich/docker-compose.override.yml
|
|
```
|
|
|
|
Example override:
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
immich-server:
|
|
environment:
|
|
- DATABASE_URL=postgresql://user:pass@localhost:5432/immich
|
|
volumes:
|
|
- /path/to/photos:/photos
|
|
```
|
|
|
|
### 5. Start the Service
|
|
|
|
```bash
|
|
# Start ComposeSync
|
|
sudo systemctl start composesync
|
|
|
|
# Enable it to start on boot
|
|
sudo systemctl enable composesync
|
|
|
|
# Check the status
|
|
sudo systemctl status composesync
|
|
```
|
|
|
|
### 6. Verify Installation
|
|
|
|
Check the logs to ensure everything is working:
|
|
|
|
```bash
|
|
# View real-time logs
|
|
sudo journalctl -u composesync -f
|
|
|
|
# Check recent logs
|
|
sudo journalctl -u composesync -n 50
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
After installation, you'll have these files:
|
|
|
|
- `/opt/composesync/update-agent.sh` - Main update script
|
|
- `/opt/composesync/config-parser.sh` - Configuration parser
|
|
- `/opt/composesync/config.toml` - TOML configuration (recommended)
|
|
- `/opt/composesync/.env` - Legacy .env configuration
|
|
- `/opt/composesync/config.toml.example` - Example TOML configuration
|
|
|
|
## Next Steps
|
|
|
|
- **[Configuration Reference](configuration.md)** - All configuration options
|
|
- **[Multi-Stack Setup](multi-stack.md)** - Managing multiple stacks
|
|
- **[Safety Features](safety-features.md)** - Rollback and error handling
|
|
- **[Monitoring](monitoring.md)** - Logs and service management |