diff --git a/assets/css/components.css b/assets/css/components.css index 0398544f06eb..108134dd29ac 100644 --- a/assets/css/components.css +++ b/assets/css/components.css @@ -95,7 +95,7 @@ } } .button { - @apply mt-1 inline-block rounded-sm bg-blue-500 p-1 px-3 text-blue-50 text-white hover:bg-blue-600 dark:bg-blue-500 hover:dark:bg-blue-400; + @apply my-2 mr-2 inline-block rounded-sm bg-blue-500 p-1 px-3 text-blue-50 text-white hover:bg-blue-600 dark:bg-blue-500 hover:dark:bg-blue-400; } .summary-bar { diff --git a/content/includes/gordondhi.md b/content/includes/gordondhi.md new file mode 100644 index 000000000000..909be24cd51d --- /dev/null +++ b/content/includes/gordondhi.md @@ -0,0 +1,28 @@ +1. Ensure Gordon is [enabled](/manuals/ai/gordon.md#enable-ask-gordon). +1. In Gordon's Toolbox, ensure Gordon's [Developer MCP toolkit is enabled](/manuals/ai/gordon/mcp/built-in-tools.md#configuration). +1. In the terminal, navigate to the directory containing your Dockerfile. +1. Start a conversation with Gordon: + ```bash + docker ai + ``` +1. Type: + ```console + "Migrate my dockerfile to DHI" + ``` +1. Follow the conversation with Gordon. Gordon will edit your Dockerfile, so when + it requests access to the filesystem and more, type `yes` to allow Gordon to proceed. + + > [!NOTE] + > To learn more about Gordon's data retention and the data it + > can access, see [Gordon](/manuals/ai/gordon.md#what-data-does-gordon-access). + +When the migration is complete, you see a success message: + +```text +The migration to Docker Hardened Images (DHI) is complete. The updated Dockerfile +successfully builds the image, and no vulnerabilities were detected in the final image. +The functionality and optimizations of the original Dockerfile have been preserved. +``` + +> [!IMPORTANT] +> As with any AI tool, you must verify Gordon's edits and test your image. diff --git a/content/manuals/_index.md b/content/manuals/_index.md index 726d25917c06..ec01e323ee02 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -31,6 +31,11 @@ params: description: Run containers programmatically in your preferred programming language. icon: /icons/Testcontainers.svg link: /testcontainers/ + - title: MCP Gateway + description: Manage and secure your AI tools with a single gateway. + icon: /icons/toolkit.svg + link: /ai/mcp-gateway/ + ai: - title: Ask Gordon description: Streamline your workflow and get the most out of the Docker ecosystem with your personal AI assistant. diff --git a/content/manuals/ai/gordon/_index.md b/content/manuals/ai/gordon/_index.md index eaa6685b0d1e..403ff7a561dc 100644 --- a/content/manuals/ai/gordon/_index.md +++ b/content/manuals/ai/gordon/_index.md @@ -20,12 +20,13 @@ of the Docker ecosystem. ## Key features -Ask Gordon provides AI-powered assistance within Docker tools. It can: +Ask Gordon provides AI-powered assistance in Docker tools. It can: - Improve Dockerfiles - Run and troubleshoot containers - Interact with your images and code - Find vulnerabilities or configuration issues +- Migrate a Dockerfile to use [Docker Hardened Images](/manuals/dhi/_index.md) It understands your local environment, including source code, Dockerfiles, and images, to provide personalized and actionable guidance. @@ -104,9 +105,10 @@ If you have concerns about data collection or usage, you can ## Using Ask Gordon -The primary interfaces to Docker's AI capabilities are through the **Ask -Gordon** view in Docker Desktop, or if you prefer to use the CLI: the `docker -ai` CLI command. +You can access Gordon: + +- In Docker Desktop, in the **Ask Gordon** view. +- Via the Docker CLI, with the `docker ai` CLI command. Once you've enabled the Docker AI features, you'll also find references to **Ask Gordon** in various other places throughout the Docker Desktop user interface. @@ -122,6 +124,7 @@ ways things you can try: - [Troubleshoot a crashed container](#troubleshoot-a-crashed-container) - [Get help with running a container](#get-help-with-running-a-container) - [Improve a Dockerfile](#improve-a-dockerfile) +- [Migrate a Dockerfile to DHI](#migrate-a-dockerfile-to-dhi) For more examples, try asking Gordon directly. For example: @@ -197,6 +200,17 @@ across several dimensions: - Portability - Resource efficiency +### Migrate a Dockerfile to DHI + +Migrating your Dockerfile to use [Docker Hardened Images](/manuals/dhi/_index.md) helps you build +more secure, minimal, and production-ready containers. DHIs are designed to +reduce vulnerabilities, enforce best practices, and simplify compliance, making +them a strong foundation for secure software supply chains. + +To request Gordon's help for the migration: + +{{% include "gordondhi.md" %}} + ## Disable Ask Gordon ### For individual users diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md b/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md index ad6f1a232e8d..380bc4d872ed 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md +++ b/content/manuals/ai/mcp-catalog-and-toolkit/hub-mcp.md @@ -29,13 +29,13 @@ The Docker Hub MCP Server is a Model Context Protocol (MCP) server that interfac > which means Gordon can automatically interact with your MCP servers. ## Using other clients -If want to integrate the Docker Hub MCP Server into your own development environment, you can find the source code and installation instructions on our [GitHub repository](https://github.com/docker/hub-mcp). +If want to integrate the Docker Hub MCP Server into your own development environment, you can find the source code and installation instructions on our [GitHub repository](https://github.com/docker/hub-mcp). ## Use Claude Desktop as a client 1. Add the Docker Hub MCP Server configuration to your `claude_desktop_config.json`: -### For public repositories only: +### For public repositories only - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this repository ```json @@ -48,11 +48,13 @@ If want to integrate the Docker Hub MCP Server into your own development environ } } ``` -### For authenticated access (recommended): + +### For authenticated access + Replace the following values: - `YOUR_DOCKER_HUB_USERNAME` - Your Docker Hub username - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` - Your Docker Hub Personal Access Token - - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this ```json { @@ -67,12 +69,15 @@ If want to integrate the Docker Hub MCP Server into your own development environ } } ``` -2. Save the configuration file and completely restart Claude Desktop for the changes to take effect. + +1. Save the configuration file and completely restart Claude Desktop for the changes to take effect. ## Usage with VS Code + 1. Add the Docker Hub MCP Server configuration to your User Settings (JSON) file in VS Code. You can do this by opening the `Command Palette` and typing `Preferences: Open User Settings (JSON)`. -### For public repositories only: +### For public repositories only + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this repository ```json @@ -85,11 +90,13 @@ If want to integrate the Docker Hub MCP Server into your own development environ } } ``` -### For authenticated access (recommended): + +### For authenticated access + Replace the following values: - `YOUR_DOCKER_HUB_USERNAME` - Your Docker Hub username - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` - Your Docker Hub Personal Access Token - - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this + - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this ```json { @@ -105,16 +112,17 @@ If want to integrate the Docker Hub MCP Server into your own development environ } } ``` -2. Open the `Command Palette` and type `MCP: List Servers`. -3. Select `docker-hub` and select `Start Server`. + +1. Open the `Command Palette` and type `MCP: List Servers`. +1. Select `docker-hub` and select `Start Server`. ## Usage examples This section provides task-oriented examples for common operations with Docker Hub tools. +### Finding images -### Finding images ```console # Search for official images @@ -123,7 +131,7 @@ $ docker ai "Search for official nginx images on Docker Hub" # Search for lightweight images to reduce deployment size and improve performance $ docker ai "Search for minimal Node.js images with small footprint" -# Get the most recent tag of a base image +# Get the most recent tag of a base image $ docker ai "Show me the latest tag details for go" # Find a production-ready database with enterprise features and reliability @@ -133,7 +141,6 @@ $ docker ai "Search for production ready database images" $ docker ai "Help me find the right Ubuntu version for my project" ``` - ### Repository management ```console @@ -156,7 +163,8 @@ $ docker ai "Show me my most recently updated repositories" $ docker ai "Show me information about my '' repository" ``` -### Pull/push images +### Pull/push images + ```console # Pull latest PostgreSQL version diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md b/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md index d06e7a946671..298ed15794e7 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md +++ b/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md @@ -7,7 +7,7 @@ aliases: - /ai/gordon/mcp/gordon-mcp-server/ --- -The Docker MCP Toolkit enables seamless setup, management, and execution of containerized MCP servers and their connections to AI agents. It removes the friction from tool usage by offering secure defaults, one-click setup, and support for a growing ecosystem of LLM-based clients. It is the fastest path from MCP tool discovery to local execution. +The Docker MCP Toolkit is a gateway that enables seamless setup, management, and execution of containerized MCP servers and their connections to AI agents. It removes the friction from tool usage by offering secure defaults, one-click setup, and support for a growing ecosystem of LLM-based clients. It is the fastest path from MCP tool discovery to local execution. ## Key features @@ -18,7 +18,7 @@ The Docker MCP Toolkit enables seamless setup, management, and execution of cont ## How the MCP toolkit works -MCP introduces two core concepts: MCP clients and MCP servers. +MCP introduces two core concepts: MCP clients and MCP servers. - MCP clients are typically embedded in LLM-based applications, such as the Claude Desktop App. They request resources or actions. @@ -55,7 +55,7 @@ surfaces and ensure safe runtime behavior. ### Passive security -- Image signing and attestation: All MCP server images under `mcp/` in the [catalog](catalog.md) +- Image signing and attestation: All MCP server images under `mcp/` in the [catalog](catalog.md) are built by Docker and digitally signed to verify their source and integrity. Each image includes a Software Bill of Materials (SBOM) for full transparency. @@ -95,7 +95,7 @@ To install an MCP server: When you select a server you can see the following information: - - Tool name and description + - Tool name and description - Partner/publisher - The list of callable tools the server provides. @@ -140,21 +140,21 @@ Your client can now interact with the MCP Toolkit. ### Example: Use Claude Desktop as a client -Imagine you have Claude Desktop installed, and you want to use the GitHub MCP server, +Imagine you have Claude Desktop installed, and you want to use the GitHub MCP server, and the Puppeteer MCP server, you do not have to install the servers in Claude Desktop. You can simply install these 2 MCP servers in the MCP Toolkit, and add Claude Desktop as a client: 1. From the **MCP Toolkit** menu, select the **Catalog** tab and find the **Puppeteer** server and add it. 2. Repeat for the **GitHub Official** server. -3. From the **Clients** tab, select **Connect** next to **Claude Desktop**. Restart +3. From the **Clients** tab, select **Connect** next to **Claude Desktop**. Restart Claude Desktop if it's running, and it can now access all the servers in the MCP Toolkit. 4. Within Claude Desktop, run a test by submitting the following prompt using the Sonnet 3.5 model: ```text Take a screenshot of docs.docker.com and then invert the colors ``` -5. From the **Clients** tab, select **Connect** next to **Claude Desktop**. Restart +5. From the **Clients** tab, select **Connect** next to **Claude Desktop**. Restart Claude Desktop if it's running, and it can now access all the servers in the MCP Toolkit. 6. Within Claude Desktop, run a test by submitting the following prompt using the Sonnet 3.5 model: @@ -173,7 +173,7 @@ You can interact with all your installed MCP servers in VS Code: {{< tab name="Enable globally">}} 1. Insert the following in your VS Code's User`settings.json`: - + ```json "mcp": { "servers": { @@ -195,11 +195,11 @@ You can interact with all your installed MCP servers in VS Code: 1. In your terminal, navigate to your project's folder. 1. Run: - + ```bash docker mcp client connect vscode ``` - + > [!NOTE] > This command creates a `.vscode/mcp.json` file in the current directory. We > recommend you add it to your `.gitignore` file. @@ -208,7 +208,7 @@ You can interact with all your installed MCP servers in VS Code: {{}} 1. In Visual Studio Code, open a new Chat and select the **Agent** mode: - + ![Copilot mode switching](./images/copilot-mode.png) 1. You can also check the available MCP tools: @@ -224,7 +224,7 @@ You can connect the MCP Toolkit to your development workflow via OAuth integration. For now, the MCP Toolkit only supports GitHub OAuth. 1. On https://github.com/, ensure you are signed in. -1. In Docker Desktop, select **MCP Toolkit** and select the **OAuth** tab. +1. In Docker Desktop, select **MCP Toolkit** and select the **OAuth** tab. 1. In the GitHub entry, select **Authorize**. Your browser opens the GitHub authorization page. 1. In the GitHub authorization page, select **Authorize Docker**. Once the authorization is successful, you are automatically redirected to Docker Desktop. @@ -232,3 +232,7 @@ OAuth integration. For now, the MCP Toolkit only supports GitHub OAuth. The MCP Toolkit now has access to your GitHub account. To revoke access, select **Revoke** in the **OAuth** tab. See an example in [Use the **GitHub Official** MCP server](#example-use-the-github-official-mcp-server). + +## Related pages + +- [Open-source MCP Gateway](/manuals/ai/mcp-gateway/_index.md) diff --git a/content/manuals/ai/mcp-gateway/_index.md b/content/manuals/ai/mcp-gateway/_index.md new file mode 100644 index 000000000000..36fbac551a51 --- /dev/null +++ b/content/manuals/ai/mcp-gateway/_index.md @@ -0,0 +1,110 @@ +--- +title: MCP Gateway +description: "Docker's MCP Gateway provides secure, centralized, and scalable orchestration of AI tools through containerized MCP servers—empowering developers, operators, and security teams." +keywords: MCP Gateway +params: + sidebar: + group: Open source +--- + +The MCP Gateway is Docker's open-source enterprise-ready solution for orchestrating and +managing [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) servers +securely across development and production environments. +It is designed to help organizations connect MCP servers from the [Docker MCP Catalog](https://hub.docker.com/mcp) to MCP Clients without compromising security, visibility, or control. + +By unifying multiple MCP servers into a single, secure endpoint, the MCP Gateway offers +the following benefits: + +- Secure by default: MCP servers run in isolated Docker containers with restricted + privileges, network access, and resource usage. +- Unified management: One gateway endpoint centralizes configuration, credentials, + and access control for all MCP servers. +- Enterprise observability: Built-in monitoring, logging, and filtering tools ensure + full visibility and governance of AI tool activity. + +## Who is the MCP Gateway designed for? + +The MCP Gateway solves problems encountered by various groups: + +- Developers: Deploy MCP servers locally and in production using Docker Compose, + with built-in support for protocol handling, credential management, and security policies. +- Security teams: Achieve enterprise-grade isolation and visibility into AI tool + behavior and access patterns. +- Operators: Scale effortlessly from local development environments to production + infrastructure with consistent, low-touch operations. + +## Key features + +- Server management: List, inspect, and call MCP tools, resources and prompts from multiple servers +- Container-based servers: Run MCP servers as Docker containers with proper isolation +- Secrets management: Secure handling of API keys and credentials via Docker Desktop +- Dynamic discovery and reloading: Automatic tool, prompt, and resource discovery from running servers +- Monitoring: Built-in logging and call tracing capabilities + +## Install a pre-release version of the MCP Gateway + +If you use Docker Desktop, the MCP Gateway is readily available. Use the +following instructions to test pre-release versions. + +### Prerequisites + +- Docker Desktop with the [MCP Toolkit feature enabled](../mcp-catalog-and-toolkit/toolkit.md#enable-docker-mcp-toolkit). +- Go 1.24+ (for development) + +### Install using a pre-built binary + +You can download the latest binary from the [GitHub releases page](https://github.com/docker/mcp-gateway/releases/latest). + +Rename the relevant binary and copy it to the destination matching your OS: + +| OS | Binary name | Destination folder | +|---------|---------------------|-------------------------------------| +| Linux | `docker-mcp` | `$HOME/.docker/cli-plugins` | +| macOS | `docker-mcp` | `$HOME/.docker/cli-plugins` | +| Windows | `docker-mcp.exe` | `%USERPROFILE%\.docker\cli-plugins` | + +Or copy it into one of these folders for installing it system-wide: + + +{{< tabs group="" >}} +{{< tab name="On Unix environments">}} + + +* `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins` +* `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins` + +> [!NOTE] +> You may have to make the binaries executable with `chmod +x`: + +> ```bash +> $ chmod +x ~/.docker/cli-plugins/docker-mcp +> ``` + +{{< /tab >}} +{{< tab name="On Windows">}} + +* `C:\ProgramData\Docker\cli-plugins` +* `C:\Program Files\Docker\cli-plugins` + +{{< /tab >}} +{{}} + +You can now use the `mcp` command: + +```bash +docker mcp --help +``` + +## Use the MCP Gateway + +Run: + +```bash +docker mcp gateway run +``` + +To view all the commands and configuration options, go to the [mcp-gateway repository](https://github.com/docker/mcp-gateway?tab=readme-ov-file#usage). + +## Related pages + +- [Docker MCP toolkit and catalog](/manuals/ai/mcp-catalog-and-toolkit/_index.md) diff --git a/content/manuals/dhi/features/integration.md b/content/manuals/dhi/features/integration.md index 9ab6340ff2c2..b33a20ad8166 100644 --- a/content/manuals/dhi/features/integration.md +++ b/content/manuals/dhi/features/integration.md @@ -78,4 +78,4 @@ and CI to scanning and deployment. They: - Include security metadata that plugs into your existing compliance systems This means you can adopt stronger security controls without disrupting your -engineering workflows. \ No newline at end of file +engineering workflows. diff --git a/content/manuals/dhi/how-to/migrate.md b/content/manuals/dhi/how-to/migrate.md index ba1710767f23..22b1d825d35f 100644 --- a/content/manuals/dhi/how-to/migrate.md +++ b/content/manuals/dhi/how-to/migrate.md @@ -9,7 +9,9 @@ keywords: migrate dockerfile, hardened base image, multi-stage build, non-root c {{< summary-bar feature_name="Docker Hardened Images" >}} This guide helps you migrate your existing Dockerfiles to use Docker Hardened -Images (DHIs). DHIs are minimal and security-focused, which may require +Images (DHIs) [manually](#step-1-update-the-base-image-in-your-dockerfile), +or with [Gordon](#use-gordon). +DHIs are minimal and security-focused, which may require adjustments to your base images, build process, and runtime configuration. This guide focuses on migrating framework images, such as images for building @@ -240,3 +242,10 @@ ENTRYPOINT [ "python", "/app/image.py" ] {{< /tab >}} {{< /tabs >}} + +### Use Gordon + +Alternatively, you can request assistance to +[Gordon](/manuals/ai/gordon/_index.md), Docker's AI-powered assistant, to migrate your Dockerfile: + +{{% include "gordondhi.md" %}} diff --git a/content/reference/compose-file/_index.md b/content/reference/compose-file/_index.md index b9624cb6ef01..68b7abdf77bc 100644 --- a/content/reference/compose-file/_index.md +++ b/content/reference/compose-file/_index.md @@ -45,7 +45,7 @@ aliases: The Compose Specification is the latest and recommended version of the Compose file format. It helps you define a [Compose file](/manuals/compose/intro/compose-application-model.md) which is used to configure your Docker application’s services, networks, volumes, and more. -Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose V2) of the Docker Compose CLI. +Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose v2) of the Docker Compose CLI. The Compose Specification on Docker Docs is the Docker Compose implementation. If you wish to implement your own version of the Compose Specification, see the [Compose Specification repository](https://github.com/compose-spec/compose-spec). diff --git a/content/reference/compose-file/build.md b/content/reference/compose-file/build.md index ed0b9d5f97e2..903f714f7525 100644 --- a/content/reference/compose-file/build.md +++ b/content/reference/compose-file/build.md @@ -49,7 +49,7 @@ services: When used to build service images from source, the Compose file creates three Docker images: -* `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder throws an error. +* `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder returns an error. * `example/database`: A Docker image is built using `backend` sub-directory within the Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file's parent folder, so `backend.Dockerfile` is a sibling file. * A Docker image is built using the `custom` directory with the user's `$HOME` as the Docker context. Compose displays a warning about the non-portable path used to build image. diff --git a/content/reference/compose-file/configs.md b/content/reference/compose-file/configs.md index c8251406beb0..99a22479e9ab 100644 --- a/content/reference/compose-file/configs.md +++ b/content/reference/compose-file/configs.md @@ -1,6 +1,6 @@ --- title: Configs top-level elements -description: Explore all the attributes the configs top-level element can have. +description: Manage and share configuration data using the configs element in Docker Compose. keywords: compose, compose specification, configs, compose file reference aliases: - /compose/compose-file/08-configs/ diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md index 602a4af09a49..b9b7f4bbd305 100644 --- a/content/reference/compose-file/deploy.md +++ b/content/reference/compose-file/deploy.md @@ -132,7 +132,7 @@ services: `resources` configures physical resource constraints for container to run on platform. Those constraints can be configured as: -- `limits`: The platform must prevent the container to allocate more. +- `limits`: The platform must prevent the container from allocating more resources. - `reservations`: The platform must guarantee the container can allocate at least the configured amount. ```yml @@ -270,7 +270,7 @@ deploy: ### `rollback_config` -`rollback_config` configures how the service should be rollbacked in case of a failing update. +`rollback_config` configures how the service should be rolled back in case of a failing update. - `parallelism`: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously. - `delay`: The time to wait between each container group's rollback (default 0s). diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md index ba4c5c0c32d4..6ad7de6e04aa 100644 --- a/content/reference/compose-file/develop.md +++ b/content/reference/compose-file/develop.md @@ -43,8 +43,6 @@ services: ## Attributes - - The `develop` subsection defines configuration options that are applied by Compose to assist you during development of a service with optimized workflows. ### `watch` @@ -90,7 +88,7 @@ services: #### `ignore` -The `ignore` attribute can be used to define a list of patterns for paths to be ignored. Any updated file +The `ignore` attribute is used to define a list of patterns for paths to be ignored. Any updated file that matches a pattern, or belongs to a folder that matches a pattern, won't trigger services to be re-created. The syntax is the same as `.dockerignore` file: @@ -106,7 +104,7 @@ for the `ignores` file, and values set in the Compose model are appended. It is sometimes easier to select files to be watched instead of declaring those that shouldn't be watched with `ignore`. -The `include` attribute can be used to define a pattern, or a list of patterns, for paths to be considered for watching. +The `include` attribute is used to define a pattern, or a list of patterns, for paths to be considered for watching. Only files that match these patterns will be considered when applying a watch rule. The syntax is the same as `ignore`. ```yaml @@ -117,10 +115,15 @@ services: watch: # rebuild image and recreate service - path: ./src - include: *.go + include: "*.go" action: rebuild ``` +> [!NOTE] +> +> In many cases `include` patterns start with a wildcard (`*`) character. This has special meaning in YAML syntax +> to define an [alias node](https://yaml.org/spec/1.2.2/#alias-nodes) so you have to wrap pattern expression with quotes. + #### `path` `path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file diff --git a/content/reference/compose-file/extension.md b/content/reference/compose-file/extension.md index 9ad4fee12fad..b7dde48cd9df 100644 --- a/content/reference/compose-file/extension.md +++ b/content/reference/compose-file/extension.md @@ -1,6 +1,6 @@ --- title: Extensions -description: Understand how to use extensions +description: Define and reuse custom fragments with extensions in Docker Compose keywords: compose, compose specification, extensions, compose file reference aliases: - /compose/compose-file/11-extension/ @@ -117,7 +117,7 @@ services: > > In the example above, the environment variables are declared using the `FOO: BAR` mapping syntax, while the sequence syntax `- FOO=BAR` is only valid when no fragments are involved. -## Informative Historical Notes +## Informative historical notes This section is informative. At the time of writing, the following prefixes are known to exist: diff --git a/content/reference/compose-file/fragments.md b/content/reference/compose-file/fragments.md index 29cc060f9814..d69e639a4546 100644 --- a/content/reference/compose-file/fragments.md +++ b/content/reference/compose-file/fragments.md @@ -1,6 +1,6 @@ --- title: Fragments -description: Understand how to use fragments +description: Reuse configuration with YAML anchors and fragments keywords: compose, compose specification, fragments, compose file reference aliases: - /compose/compose-file/10-fragments/ diff --git a/content/reference/compose-file/include.md b/content/reference/compose-file/include.md index a04edb353004..f1a01d925318 100644 --- a/content/reference/compose-file/include.md +++ b/content/reference/compose-file/include.md @@ -1,6 +1,7 @@ --- -title: Include -description: Learn about include +linkTitle: Include +title: Use include to modularize Compose files +description: Reference external Compose files using the include top-level element keywords: compose, compose specification, include, compose file reference aliases: - /compose/compose-file/14-include/ @@ -9,10 +10,10 @@ weight: 110 {{< summary-bar feature_name="Composefile include" >}} -A Compose application can declare dependency on another Compose application. This is useful if: +You can reuse and modularize Docker Compose configurations by including other Compose files. This is useful if: - You want to reuse other Compose files. - You need to factor out parts of your application model into separate Compose files so they can be managed separately or shared with others. -- Teams need to keep a Compose file reasonably complicated for the limited amount of resources it has to declare for its own sub-domain within a larger deployment. +- Teams need to maintain a Compose file with only necessary complexity for the limited amount of resources it has to declare for its own sub-domain within a larger deployment. The `include` top-level section is used to define the dependency on another Compose application, or sub-domain. Each path listed in the `include` section is loaded as an individual Compose application model, with its own project directory, in order to resolve relative paths. diff --git a/content/reference/compose-file/interpolation.md b/content/reference/compose-file/interpolation.md index 23b3fd585237..24727daf3f81 100644 --- a/content/reference/compose-file/interpolation.md +++ b/content/reference/compose-file/interpolation.md @@ -1,6 +1,6 @@ --- title: Interpolation -description: Learn about interpolation +description: Substitute environment variables in Docker Compose files using interpolation syntax. keywords: compose, compose specification, interpolation, compose file reference aliases: - /compose/compose-file/12-interpolation/ diff --git a/content/reference/compose-file/merge.md b/content/reference/compose-file/merge.md index 7b9a5784831d..3c1cb1f41164 100644 --- a/content/reference/compose-file/merge.md +++ b/content/reference/compose-file/merge.md @@ -1,6 +1,7 @@ --- -title: Merge -description: Learn about merging rules +linkTitle: Merge +title: Merge Compose files +description: Understand how Docker Compose merges multiple files and resolves conflicts keywords: compose, compose specification, merge, compose file reference aliases: - /compose/compose-file/13-merge/ diff --git a/content/reference/compose-file/models.md b/content/reference/compose-file/models.md index 23f528dd27cd..8331a57e2bcc 100644 --- a/content/reference/compose-file/models.md +++ b/content/reference/compose-file/models.md @@ -2,7 +2,7 @@ title: Models description: Learn about the models top-level element keywords: compose, compose specification, models, compose file reference -weight: 120 +weight: 130 --- {{< summary-bar feature_name="Compose models" >}} diff --git a/content/reference/compose-file/networks.md b/content/reference/compose-file/networks.md index c8c30a3e1b58..f70cdbde6cd4 100644 --- a/content/reference/compose-file/networks.md +++ b/content/reference/compose-file/networks.md @@ -1,6 +1,7 @@ --- -title: Networks top-level elements -description: Explore all the attributes the networks top-level element can have. +linkTitle: Networks +title: Define and manage networks in Docker Compose +description: Learn how to configure and control networks using the top-level networks element in Docker Compose. keywords: compose, compose specification, networks, compose file reference aliases: - /compose/compose-file/06-networks/ @@ -60,7 +61,7 @@ networks: driver: custom-driver ``` -The advanced example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both. +This example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both. ## The default network @@ -170,7 +171,7 @@ Compose doesn't attempt to create these networks, and returns an error if one do - All other attributes apart from name are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid. In the following example, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose -queries the platform for an existing network simply called `outside` and connects the +queries the platform for an existing network called `outside` and connects the `proxy` service's containers to it. ```yml diff --git a/content/reference/compose-file/profiles.md b/content/reference/compose-file/profiles.md index 144c6fd75628..37acdcf00580 100644 --- a/content/reference/compose-file/profiles.md +++ b/content/reference/compose-file/profiles.md @@ -1,5 +1,6 @@ --- -title: Profiles +linkTitle: Profiles +title: Learn how to use profiles in Docker Compose description: Learn about profiles keywords: compose, compose specification, profiles, compose file reference aliases: @@ -52,7 +53,7 @@ services: In the above example: -- If the Compose application model is parsed with no profile enabled, it only contains the `web` service. +- If the Compose application model is parsed when no profile is enabled, it only contains the `web` service. - If the profile `test` is enabled, the model contains the services `test_lib` and `coverage_lib`, and service `web`, which is always enabled. - If the profile `debug` is enabled, the model contains both `web` and `debug_lib` services, but not `test_lib` and `coverage_lib`, and as such the model is invalid regarding the `depends_on` constraint of `debug_lib`. @@ -68,4 +69,4 @@ In the above example: profile `debug` is automatically enabled and service `test_lib` is pulled in as a dependency starting both services `debug_lib` and `test_lib`. -See how you can use `profiles` in [Docker Compose](/manuals/compose/how-tos/profiles.md). +Learn how to use `profiles` in [Docker Compose](/manuals/compose/how-tos/profiles.md). diff --git a/content/reference/compose-file/secrets.md b/content/reference/compose-file/secrets.md index 5fe118b77b20..f198623a31eb 100644 --- a/content/reference/compose-file/secrets.md +++ b/content/reference/compose-file/secrets.md @@ -1,5 +1,5 @@ --- -title: Secrets top-level elements +title: Secrets description: Explore all the attributes the secrets top-level element can have. keywords: compose, compose specification, secrets, compose file reference aliases: diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index eed8488b10ad..2e9a14532858 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -1,5 +1,6 @@ --- -title: Services top-level elements +linkTitle: Services +title: Define services in Docker Compose description: Explore all the attributes the services top-level element can have. keywords: compose, compose specification, services, compose file reference aliases: @@ -1290,7 +1291,7 @@ There is a performance penalty for applications that swap memory to disk often. - If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host container has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap. - If `memswap_limit` is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system. -### models +### `models` {{< summary-bar feature_name="Compose models" >}} @@ -1358,7 +1359,7 @@ services: ``` For more information about the `networks` top-level element, see [Networks](networks.md). -### Implicit default network +#### Implicit default network If `networks` is empty or absent from the Compose file, Compose considers an implicit definition for the service to be connected to the `default` network: @@ -1674,7 +1675,7 @@ expressed in the short form. - `protocol`: The port protocol (`tcp` or `udp`). Defaults to `tcp`. - `app_protocol`: The application protocol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands. Introduced in Docker Compose version [2.26.0](/manuals/compose/releases/release-notes.md#2260). - `mode`: Specifies how the port is published in a Swarm setup. If set to `host`, it publishes the port on every node in Swarm. If set to `ingress`, it allows load balancing across the nodes in Swarm. Defaults to `ingress`. -- `name`: A human-readable name for the port, used to document it's usage within the service. +- `name`: A human-readable name for the port, used to document its usage within the service. ```yml ports: @@ -1783,12 +1784,12 @@ The mechanism used by Compose to delegate the service lifecycle to an external b For more information on using the `provider` attribute, see [Use provider services](/manuals/compose/how-tos/provider-services.md). -### `type` +#### `type` `type` attribute is required. It defines the external component used by Compose to manage setup and tear down lifecycle events. -### `options` +#### `options` `options` are specific to the selected provider and not validated by the compose specification diff --git a/content/reference/compose-file/version-and-name.md b/content/reference/compose-file/version-and-name.md index cb5bd689ab3d..aaf992c56b65 100644 --- a/content/reference/compose-file/version-and-name.md +++ b/content/reference/compose-file/version-and-name.md @@ -9,10 +9,11 @@ weight: 10 ## Version top-level element (obsolete) -The top-level `version` property is defined by the Compose Specification for backward compatibility. It is only informative and you'll receive a warning message that it is obsolete if used. +> [!IMPORTANT] +> +> The top-level `version` property is defined by the Compose Specification for backward compatibility. It is only informative and you'll receive a warning message that it is obsolete if used. -Compose doesn't use `version` to select an exact schema to validate the Compose file, but -prefers the most recent schema when it's implemented. +Compose always uses the most recent schema to validate the Compose file, regardless of the `version` field. Compose validates whether it can fully parse the Compose file. If some fields are unknown, typically because the Compose file was written with fields defined by a newer version of the Specification, you'll receive a warning message. @@ -20,6 +21,7 @@ because the Compose file was written with fields defined by a newer version of t ## Name top-level element The top-level `name` property is defined by the Compose Specification as the project name to be used if you don't set one explicitly. + Compose offers a way for you to override this name, and sets a default project name to be used if the top-level `name` element is not set. diff --git a/content/reference/compose-file/volumes.md b/content/reference/compose-file/volumes.md index 2003f488761a..64e826f58003 100644 --- a/content/reference/compose-file/volumes.md +++ b/content/reference/compose-file/volumes.md @@ -1,6 +1,7 @@ --- -title: Volumes top-level element -description: Explore all the attributes the volumes top-level element can have. +linkTitle: Volumes +title: Define and manage volumes in Docker Compose +description: Control how volumes are declared and shared between services using the top-level volumes element. keywords: compose, compose specification, volumes, compose file reference aliases: - /compose/compose-file/07-volumes/