portainer-core/docs/reference/scripts.md

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

# 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:

# 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:

./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:

./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:

# 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:

./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 for comprehensive backup strategy.

Disk Usage (disk-usage.sh)

Reports disk usage breakdown for SSD and HDD storage.

Usage:

./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:

./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:

./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 - Comprehensive backup strategy
• Stacks Reference - Stack deployment and management
• Automation Reference - Portainer REST API automation