Content Sync Automation
Relevant source files
The following files were used as context for generating this wiki page:Content Sync Automation in the Docker documentation project refers to the systems and processes that automatically update content from external, authoritative sources. This ensures that reference documentation, such as for the CLI and API, remains accurate and aligned with the source code without manual intervention. This automation is critical for maintaining the integrity of the documentation, as some content is "vendored" and treated as read-only within this repository.
A distinct but related concept is the developer-facing content sync feature, Compose Watch, which automates updating running containers based on local file changes. This wiki page covers both the internal documentation sync mechanisms and the developer-facing sync features documented within the project.
Sources: agent.yml:30-36, CONTRIBUTING.md:46-49
Documentation Sync Architecture
The primary goal of documentation sync is to pull in content from various upstream repositories, which are the source of truth for specific documentation sections. This content is considered "vendored" or "read-only" and should not be edited directly within the docker/docs repository.
Sources: agent.yml:30-36, CONTRIBUTING.md:46-49
Vendored and Generated Content
Several key documentation sections are managed externally. Updates to this content must be made in the corresponding upstream repository. The agent.yml file defines an automated agent responsible for coordinating documentation work, which is programmed to recognize and differentiate between local and vendored content.
The following diagram illustrates the relationship between upstream repositories and the documentation content.
This diagram shows that various upstream repositories feed into the Docker Docs repository, which then uses Hugo to build the final documentation site.
Sources: agent.yml:30-36, 76-83, CONTRIBUTING.md:46-56, content/reference/cli/docker/README.md:5-10
The mapping between content and its source is critical for contributors to understand where to direct their changes.
| Documentation Section | Upstream Source Repository |
|---|---|
| CLI Reference (docker) | docker/cli |
| Buildx Reference | docker/buildx |
| Compose Reference | docker/compose |
| Model Runner Reference | docker/model-runner |
| Dockerfile Reference | moby/buildkit |
| Engine API Reference | moby/moby |
Sources: agent.yml:76-83, CONTRIBUTING.md:50-53
CLI Reference Generation Process
The CLI reference documentation provides a specific example of this sync process. The content is not written in Markdown directly. Instead, it is generated from YAML files located in the _data/engine-cli directory. These YAML files are, in turn, generated from the docker/cli source code and its associated documentation files.
The process is as follows:
- The
docker/clirepository contains the source code and extended descriptions for each command. - A process (external to this repo) generates YAML files from the
docker/clisource. - These YAML files are placed into the
docker/docsrepository. - Hugo uses these YAML files and a stub file (
/_includes/cli.md) to render the final HTML pages for the CLI reference.
This flow ensures that the command descriptions, usage, and examples are always synchronized with the CLI's actual implementation.
Sources: content/reference/cli/docker/README.md:5-20
Automated Agent Coordination
The project uses an AI agent system to manage documentation updates. The root agent acts as a coordinator that understands the distinction between local and vendored content. When a user requests a change, this agent can identify if the target content is read-only and must be changed upstream.
The following sequence diagram shows how the agent handles a request to update CLI documentation.
This diagram illustrates the agent's role in enforcing the read-only nature of vendored content and directing contributors to the correct repository.
Sources: agent.yml:6-12, 53-74
Developer Workflow Sync: Compose Watch
Separate from the documentation's internal content management, the project documents a powerful content sync feature for developers: Compose Watch. This feature, configured via the develop section in a compose.yml file, automatically updates running services based on changes to local source files.
Sources: content/reference/compose-file/develop.md:1-12
Watch Configuration
The develop.watch attribute defines a list of rules that monitor for file changes and trigger specific actions.
The basic flow of Compose Watch is shown below.
This flowchart shows the logic Compose Watch uses to decide whether to trigger an action upon a file change.
Sources: content/reference/compose-file/develop.md:27-30, 68-98
Watch Actions
The action key determines what Compose does when a file change is detected.
| Action | Description | Available Since |
|---|---|---|
rebuild | Rebuilds the service image and recreates the service's containers. | - |
restart | Restarts the service container without rebuilding the image. | v2.32.0 |
sync | Synchronizes the changed files from the local path to the target directory inside the container. | - |
sync+restart | Performs a sync and then restarts the service container. | v2.23.0 |
sync+exec | Performs a sync and then executes a specified command inside the container. | v2.32.0 |
Sources: content/reference/compose-file/develop.md:32-44
An example configuration for sync+exec:
services:
frontend:
image: ...
develop:
watch:
# sync content then run command to reload service without interruption
- path: ./etc/config
action: sync+exec
target: /etc/config/
exec:
command: app reload
Sources: content/reference/compose-file/develop.md:65-67
Conclusion
The docker-docs project employs two distinct forms of content sync automation. Internally, it uses a robust system of vendoring and generation to keep reference documentation synchronized with upstream source-of-truth repositories, a process overseen by automated agents. Externally, it provides developers with the powerful Compose Watch feature, enabling a rapid, iterative development cycle by synchronizing local file changes directly with running containers. Both systems are essential for maintaining accuracy and improving developer efficiency.
Sources: agent.yml, content/reference/compose-file/develop.md