# 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