---
name: docker-maintenance-manual
description: 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
```bash
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)
```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.