restructure documentation

2025-11-20 10:17:09 +01:00
parent cb428a885d
commit 0e3fef20fc
28 changed files with 1332 additions and 402 deletions
@@ -0,0 +1,200 @@
+# Maintenance Scripts Reference
+
+Shell scripts for common maintenance tasks located in `/scripts/`.
+
+## Available Scripts
+
+| Script | Description | Usage |
+|--------|-------------|-------|
+| `gpu-check.sh` | Verify GPU passthrough in containers | `./scripts/gpu-check.sh` |
+| `health-check.sh` | Check all services and report status | `./scripts/health-check.sh` |
+| `setup-kuma-monitors.sh` | Manual guide for configuring Uptime Kuma monitors | `./scripts/setup-kuma-monitors.sh` |
+| `setup-kuma-monitors.py` | **Automated** Uptime Kuma monitor setup via API | `source .venv/bin/activate && python3 scripts/setup-kuma-monitors.py` |
+| `backup-configs.sh` | Backup all Docker configs | `./scripts/backup-configs.sh` |
+| `disk-usage.sh` | Report disk usage for SSD and HDD | `./scripts/disk-usage.sh` |
+| `update-stacks.sh` | Pull latest images and update containers | `./scripts/update-stacks.sh <stack-name>` |
+| `cleanup.sh` | Clean up unused Docker resources | `./scripts/cleanup.sh` |
+
+## Making Scripts Executable
+
+```bash
+# Make all scripts executable
+chmod +x scripts/*.sh
+
+# Or individually
+chmod +x scripts/health-check.sh
+```
+
+## Scheduling with Cron
+
+Add to crontab for automated maintenance:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Examples:
+# Daily health check at 8 AM
+0 8 * * * /home/jpmschweitzer/Projects/portainer-core/scripts/health-check.sh >> /var/log/portainer-core-health.log 2>&1
+
+# Weekly cleanup on Sunday at 3 AM
+0 3 * * 0 /home/jpmschweitzer/Projects/portainer-core/scripts/cleanup.sh
+
+# Daily backup at 2 AM
+0 2 * * * /home/jpmschweitzer/Projects/portainer-core/scripts/backup-configs.sh
+```
+
+## Script Details
+
+### GPU Check (`gpu-check.sh`)
+
+Verifies GPU passthrough is working in GPU-enabled containers (Ollama, Jellyfin).
+
+**Usage:**
+```bash
+./scripts/gpu-check.sh
+```
+
+**Output:**
+- Lists all running containers with GPU access
+- Runs `nvidia-smi` inside each container
+- Reports any containers that fail GPU detection
+
+### Health Check (`health-check.sh`)
+
+Checks status of all deployed services and generates a health report.
+
+**Usage:**
+```bash
+./scripts/health-check.sh
+```
+
+**Checks:**
+- Container running status
+- Container health status (if health check defined)
+- Port accessibility
+- Basic connectivity tests
+
+### Uptime Kuma Monitor Setup
+
+Two versions available:
+
+**Manual Script (`setup-kuma-monitors.sh`):**
+- Interactive guide for adding monitors
+- Shows recommended settings for each service
+- Good for understanding monitor configuration
+
+**Automated Script (`setup-kuma-monitors.py`):**
+- Python script using Uptime Kuma API
+- Automatically creates monitors for all services
+- Requires Uptime Kuma API key
+
+**Usage:**
+```bash
+# Automated setup
+source .venv/bin/activate
+python3 scripts/setup-kuma-monitors.py
+```
+
+### Backup Configs (`backup-configs.sh`)
+
+Backs up Docker container configurations and important data.
+
+**Usage:**
+```bash
+./scripts/backup-configs.sh
+```
+
+**What it backs up:**
+- Docker Compose files from `/stacks/`
+- Container configs from `/home/jpmschweitzer/docker-data/`
+- Project documentation
+- Excludes large media files (those are backed up separately)
+
+**Backup location:**
+- `/mnt/media/backups/portainer-core/`
+
+See [Backup Procedures](../guides/backup-procedures.md) for comprehensive backup strategy.
+
+### Disk Usage (`disk-usage.sh`)
+
+Reports disk usage breakdown for SSD and HDD storage.
+
+**Usage:**
+```bash
+./scripts/disk-usage.sh
+```
+
+**Output:**
+- Total SSD usage (`/home/jpmschweitzer/docker-data/`)
+- Total HDD usage (`/mnt/media/`)
+- Per-service breakdown
+- Available space warnings
+
+### Update Stacks (`update-stacks.sh`)
+
+Pulls latest images and updates a specific stack.
+
+**Usage:**
+```bash
+./scripts/update-stacks.sh <stack-name>
+
+# Examples:
+./scripts/update-stacks.sh jellyfin
+./scripts/update-stacks.sh core-api
+```
+
+**What it does:**
+1. Pulls latest images for the stack
+2. Stops containers gracefully
+3. Recreates containers with new images
+4. Removes old images
+5. Verifies containers started successfully
+
+**Note:** Watchtower handles this automatically for most services. Use this script for manual updates or services excluded from Watchtower.
+
+### Cleanup (`cleanup.sh`)
+
+Cleans up unused Docker resources to free disk space.
+
+**Usage:**
+```bash
+./scripts/cleanup.sh
+```
+
+**What it removes:**
+- Stopped containers
+- Unused images
+- Dangling build cache
+- Unused volumes (with confirmation prompt)
+- Unused networks
+
+**Warning:** Always review what will be removed before confirming volume deletion.
+
+## Script Guidelines
+
+All scripts follow these conventions:
+
+- Include error handling and exit codes
+- Use absolute paths for reliability
+- Log output for debugging
+- Exit with status codes (0 = success, non-zero = failure)
+- Include help text with `-h` or `--help` flags
+- Non-destructive by default (ask before deleting)
+
+## Creating New Scripts
+
+When adding new maintenance scripts:
+
+1. Place in `/scripts/` directory
+2. Use `.sh` extension for shell scripts
+3. Make executable: `chmod +x scripts/your-script.sh`
+4. Add to this documentation
+5. Include help text and error handling
+6. Test thoroughly before scheduling with cron
+
+## Related Documentation
+
+- [Backup Procedures](../guides/backup-procedures.md) - Comprehensive backup strategy
+- [Stacks Reference](stacks.md) - Stack deployment and management
+- [Automation Reference](AUTOMATION.md) - Portainer REST API automation