config-hermes/skills/docker/docker-maintenance-manual/SKILL.md

name, description

name	description
docker-maintenance-manual	Generate a comprehensive bilingual maintenance manual for all Docker containers on a VPS, including container details (image, status, ports, mounts, environment variables) and standard maintenance procedures (view logs, update image, backup volumes, check stats, restart).

Docker Maintenance Manual Generation Skill

This skill automates the creation of a detailed maintenance guide for every Docker container running on a self-hosted VPS. The output is a Markdown file with sections per container and reusable maintenance task templates, suitable for bilingual (Chinese/English) documentation.

When to Use

• You need a reference guide for all Docker services on your VPS.
• You want to document container configurations and standard operating procedures.
• You prefer a single, structured document that can be updated periodically.

Prerequisites

• Docker Engine installed and running.
• jq installed for JSON parsing (used in the script; if not available, the skill provides an alternative using only Docker formatting).
• Sufficient permissions to inspect containers.

Steps

1. List Running Containers

docker ps --format "{{.Names}}"

2. For Each Container, Extract Details

The skill uses a Bash loop to gather:

• Container name
• Image
• Status (State)
• Started at
• Restart policy
• Published ports
• Mounts/volumes (count and details)
• Key environment variables (excluding common ones like PATH, LANG)

3. Generate Markdown Sections

Each container gets a section with:

• Container Overview: Name, image, status, started time, restart policy, ports.
• Volumes/Mounts: List of source → destination.
• Environment Variables: Key variables (first few).
• Maintenance Tasks: Standard procedures with container-specific commands:
  1. View logs: docker logs -f <container>
  2. Update to latest image: pull image, stop, remove, recreate (refer to original deployment method; if using docker-compose, use docker compose pull && docker compose up -d).
  3. Backup volumes: example command using docker run to tar the volume.
  4. Check stats: docker stats <container>
  5. Restart container: docker restart <container>

4. Output to File

The generated manual is saved to a specified location (default: /tmp/docker_maintenance_manual.md).

Example Script (Bash)

#!/usr/bin/env bash
OUTPUT_FILE="${1:-/tmp/docker_maintenance_manual.md}"
> "$OUTPUT_FILE"  # Clear or create file

for container in $(docker ps --format "{{.Names}}"); do
    {
        echo "## $container"
        echo ""
        # Use docker inspect and format as needed; here we use a simple format for demonstration
        docker inspect "$container" | \
        jq -r '
        .[] | 
        {
            name: .Name[1:], 
            image: .Config.Image,
            state: .State.Status,
            started: .State.StartedAt,
            restart: .HostConfig.RestartPolicy.Name,
            ports: (.NetworkSettings.Ports | to_entries | map("\(.key): \(.value[0].HostPort)") | join(", ")) // "",
            mounts: .Mounts,
            env: .Config.Env
        } | 
        "- **\\(.name)**: \\(.image)\n  - Status: \\(.state)\n  - Started: \\(.started)\n  - Restart Policy: \\(.restart)\n  - Ports: \\(.ports // \"None\")\n  - Volumes/Mounts: (\\(.mounts | length) mounts)\n  - Key Environment Variables: (\\(.env | map(select(test(\"^(?!PATH|LANG|HOME|USER)\"))) | .[0:3] | join(\", \")) // \"None\")\n"
        ' >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "### Maintenance Tasks" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "1. **View Logs**:" >> "$OUTPUT_FILE"
        echo "   \`\`\`bash" >> "$OUTPUT_FILE"
        echo "   docker logs -f $container" >> "$OUTPUT_FILE"
        echo "   \`\`\`" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "2. **Update to Latest Image**:" >> "$OUTPUT_FILE"
        echo "   \`\`\`bash" >> "$OUTPUT_FILE"
        echo "   docker pull $(docker inspect $container --format '{{.Config.Image}}')" >> "$OUTPUT_FILE"
        echo "   docker stop $container" >> "$OUTPUT_FILE"
        echo "   docker rm $container" >> "$OUTPUT_FILE"
        echo "   # Recreate with same parameters (check original deployment method)" >> "$OUTPUT_FILE"
        echo "   # If using docker-compose: cd /path/to/compose && docker compose pull && docker compose up -d" >> "$OUTPUT_FILE"
        echo "   \`\`\`" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "3. **Backup Volumes**:" >> "$OUTPUT_FILE"
        echo "   Identify volume names from mounts above, then:" >> "$OUTPUT_FILE"
        echo "   \`\`\`bash" >> "$OUTPUT_FILE"
        echo "   # Example for backing up a volume named <volume_name>" >> "$OUTPUT_FILE"
        echo "   docker run --rm -v <volume_name>:/data -v $(pwd):/backup ubuntu tar czf /backup/<volume_name>_backup.tar.gz -C /data ." >> "$OUTPUT_FILE"
        echo "   \`\`\`" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "4. **Check Container Stats**:" >> "$OUTPUT_FILE"
        echo "   \`\`\`bash" >> "$OUTPUT_FILE"
        echo "   docker stats $container" >> "$OUTPUT_FILE"
        echo "   \`\`\`" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "5. **Restart Container**:" >> "$OUTPUT_FILE"
        echo "   \`\`\`bash" >> "$OUTPUT_FILE"
        echo "   docker restart $container" >> "$OUTPUT_FILE"
        echo "   \`\`\`" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        echo "--" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
    } done

echo "Maintenance manual generated at $OUTPUT_FILE"

Notes

• The skill assumes jq is available for pretty JSON parsing. If not, you can replace the jq section with direct docker inspect formatting using Go templates.
• The manual is generated in English; to make it bilingual, you can translate the section headers and task descriptions into Chinese, or maintain two parallel sections. The user's preference for bilingual can be accommodated by post-processing the generated file or by editing the skill to output both languages.
• Always verify container names and volume paths before running backup or update commands.
• For containers managed by Docker Compose, it is safer to use docker compose commands for updates.

Verification

• Check that the output file exists and contains sections for each running container.
• Spot-check a container's details against docker inspect <container> manually.

Maintenance

• Regenerate the manual periodically (e.g., monthly) or after significant changes to your Docker stack.
• Store the manual in a version-controlled location (e.g., Git) for tracking changes.