Add additional documentation and examples

- Usage examples for different scenarios - Network backup analysis documentation - Restore operation examples and procedures
2024-08-24 18:00:00 +02:00
parent b63de7d682
commit 7bad771a59
3 changed files with 558 additions and 0 deletions
--- a/example_usage.md
+++ b/example_usage.md
@@ -0,0 +1,110 @@
+# Docker2PBS - Usage Examples
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+chmod +x docker2pbs.py
+```
+
+## Basic Usage
+
+```bash
+./docker2pbs.py docker-compose.yml web --pbs-repository user@pbs.example.com:backup-datastore
+```
+
+## Dry-run Mode (Testing)
+
+Use `--dry-run` to see what would be executed without actually performing operations:
+
+```bash
+./docker2pbs.py docker-compose.yml web \
+    --pbs-repository user@pbs.example.com:backup-datastore \
+    --dry-run
+```
+
+## Usage with Authentication
+
+```bash
+./docker2pbs.py docker-compose.yml database \
+    --pbs-repository user@pbs.example.com:backup-datastore \
+    --pbs-username backup-user \
+    --pbs-password secret123 \
+    --pbs-fingerprint aa:bb:cc:dd:ee:ff...
+```
+
+## Dry-run with Full Configuration
+
+```bash
+./docker2pbs.py docker-compose.yml database \
+    --pbs-repository user@pbs.example.com:backup-datastore \
+    --pbs-username backup-user \
+    --pbs-password secret123 \
+    --pbs-fingerprint aa:bb:cc:dd:ee:ff... \
+    --dry-run
+```
+
+## Example docker-compose.yml
+
+```yaml
+version: '3.8'
+services:
+  web:
+    image: nginx:latest
+    volumes:
+      - ./html:/var/www/html
+      - logs_volume:/var/log/nginx
+    networks:
+      - frontend
+      - backend
+
+  database:
+    image: postgres:13
+    volumes:
+      - db_data:/var/lib/postgresql/data
+      - ./backups:/backups
+    networks:
+      - backend
+    environment:
+      POSTGRES_PASSWORD: secret
+
+volumes:
+  logs_volume:
+  db_data:
+    external: true
+
+networks:
+  frontend:
+  backend:
+    external: true
+```
+
+## What the Script Does
+
+1. **Parses docker-compose.yml** - reads service configuration
+2. **Identifies volumes** - both local and external volumes
+3. **Identifies networks** - including external networks
+4. **Stops the service** - using `docker-compose stop`
+5. **Creates PBS backup** - of all service volumes
+6. **Restarts the service** - using `docker-compose up -d`
+
+## Dry-run Mode
+
+In `--dry-run` mode, the script:
+- Shows detailed configuration summary
+- Displays all commands that would be executed
+- **DOES NOT** stop or start services
+- **DOES NOT** create actual backups
+- **DOES NOT** perform any destructive operations
+
+Perfect for testing configuration before running actual backup.
+
+## PBS Configuration
+
+Make sure you have `proxmox-backup-client` installed and configured access to PBS.
+
+## Supported Volume Types
+
+- **Bind mounts** - local paths (e.g., `./data:/app/data`)
+- **Named volumes** - Docker volumes (e.g., `db_data:/var/lib/postgresql/data`)
+- **External volumes** - externally managed volumes