Docker Compose Readme

Docker Compose README Generator Skill

Purpose

This skill automatically generates professional, comprehensive README.md files for Docker Compose projects by analyzing the configuration files and creating standardized documentation.

Activation Triggers

Use this skill when the user:

• Asks to create a README for a docker-compose folder
• Requests documentation for a container service
• Wants to update/improve existing README files
• Mentions "document this compose file" or similar requests

Process

1. Analyze Project Structure

First, identify the files in the target directory:

• compose.yml or docker-compose.yml (required)
• .env.example or .env (for environment variables)
• Existing README.md (if updating)

2. Read Configuration Files

Read the compose.yml file to extract:

• Service name(s)
• Docker image and version
• Port mappings
• Volume mounts
• Network configuration
• Environment variables
• Restart policies
• Dependencies between services

Read the .env.example file to understand:

• Required environment variables
• Default values
• Variable purposes and descriptions

3. Generate README Structure

Create a comprehensive README.md with the following sections:

Header Section

# [Service Name]

Brief description of what this service does (1-2 sentences).

Overview Section

Explain:

• What the service is
• Its primary purpose
• Key features or capabilities
• How it fits into the larger infrastructure

Prerequisites Section

List requirements:

• Docker and Docker Compose versions (if specific)
• Required networks (especially external networks)
• Dependencies on other services
• System requirements

Configuration Section

Document environment variables in a table format:

| Variable | Default | Description |
|----------|---------|-------------|
| `VAR_NAME` | `default_value` | What this variable controls |

Include instructions for:

• Copying .env.example to .env
• Customizing values
• Security considerations for secrets

Usage Section

Provide common commands:

• Starting the service: docker compose up -d
• Stopping the service: docker compose down
• Viewing logs: docker compose logs -f
• Updating: docker compose pull && docker compose up -d
• Restarting: docker compose restart

Network Configuration

Explain:

• Which networks are used
• Whether networks are external or created by compose
• How to create required networks
• Network connectivity considerations

Volumes Section (if applicable)

Document:

• What data is persisted
• Volume mount purposes
• Backup considerations
• Path mappings

Port Mappings Section (if applicable)

List:

• Exposed ports and their purposes
• How to access the service
• Default URLs or endpoints

Security Considerations

Include relevant security notes:

• Secrets management (environment variables, secrets)
• Access control recommendations
• Network security (firewall rules, exposed ports)
• Privilege escalation warnings (if mounting docker.sock)
• Update policies

Troubleshooting Section

Common issues and solutions:

• Connection problems
• Permission errors
• Configuration mistakes
• Log analysis tips

Additional Resources

Links to:

• Official documentation
• Project website
• Docker Hub image page
• Community resources

4. Writing Style Guidelines

• EXTREME concision: Sacrifice grammar for brevity. Short fragments ok. No fluff.
• Clear headings: Scannable markdown structure
• Code blocks: Bash syntax highlighting
• Tables: Env vars, config options
• Practical only: Actionable info. Skip obvious.
• Assume Docker knowledge: Explain service-specific only
• Security first: Always include security notes

5. Special Cases

Multi-Service Compose Files

When compose.yml contains multiple services:

• Create a README that covers all services
• Use subsections for service-specific configuration
• Explain how services interact
• Document dependencies and startup order

Complex Network Topologies

For advanced networking:

• Diagram the network architecture (if needed)
• Explain network isolation
• Document inter-service communication

External Dependencies

If services depend on external resources:

• Clearly document what must exist beforehand
• Provide setup instructions or links
• Explain integration points

Quality Checklist

Before completing, ensure the README includes:

• Clear title and description
• All environment variables documented
• Common usage commands provided
• Network requirements explained
• Security considerations mentioned
• Troubleshooting section included
• Links to official documentation
• Proper markdown formatting
• Accurate information from actual config files

Example Output Structure

# Service Name

One-line description.

## Overview
Detailed explanation...

## Prerequisites
- Requirement 1
- Requirement 2

## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|

## Usage
### Starting the Service
```bash
docker compose up -d

Network Configuration

Details about networks...

Security Considerations

Important security notes...

Troubleshooting

Common issues...

Additional Resources

• Official Docs

## Notes
- Always read existing files before writing/editing
- Preserve user customizations when updating existing READMEs
- Infer service purpose from image name and configuration if not obvious
- Use relative links for local file references in markdown
- Keep the tone professional but approachable