Skip to content

Commit f6bb42e

Browse files
gloursndeloofaevesdocker
authored
add how-to page explaining usage of Compose provider services (docker#22586)
<!--Delete sections as needed --> ## Description Add how-to page for Compose provider services explaining usage and configuration of this new feature allowing extending Compose behaviour ## Related issues or tickets https://docker.atlassian.net/browse/APCLI-1091 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [x] Technical review - [x] Editorial review - [ ] Product review --------- Signed-off-by: Guillaume Lours <[email protected]> Co-authored-by: Nicolas De loof <[email protected]> Co-authored-by: Allie Sadler <[email protected]>
1 parent 751d668 commit f6bb42e

File tree

2 files changed

+127
-0
lines changed

2 files changed

+127
-0
lines changed

‎content/manuals/compose/how-tos/provider-services.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Use provider services
3+
description: Learn how to use provider services in Docker Compose to integrate external capabilities into your applications
4+
keywords: compose, docker compose, provider, services, platform capabilities, integration, model runner, ai
5+
weight: 112
6+
params:
7+
sidebar:
8+
badge:
9+
color: green
10+
text: New
11+
---
12+
13+
{{< summary-bar feature_name="Compose provider services" >}}
14+
15+
Docker Compose supports provider services, which allow integration with services whose lifecycles are managed by third-party components rather than by Compose itself.
16+
This feature enables you to define and utilize platform-specific services without the need for manual setup or direct lifecycle management.
17+
18+
19+
## What are provider services?
20+
21+
Provider services are a special type of service in Compose that represents platform capabilities rather than containers.
22+
They allow you to declare dependencies on specific platform features that your application needs.
23+
24+
When you define a provider service in your Compose file, Compose works with the platform to provision and configure
25+
the requested capability, making it available to your application services.
26+
27+
## Using provider services
28+
29+
To use a provider service in your Compose file, you need to:
30+
31+
1. Define a service with the `provider` attribute
32+
2. Specify the `type` of provider you want to use
33+
3. Configure any provider-specific options
34+
4. Declare dependencies from your application services to the provider service
35+
36+
Here's a basic example:
37+
38+
```yaml
39+
services:
40+
database:
41+
provider:
42+
type: awesomecloud
43+
options:
44+
type: mysql
45+
foo: bar
46+
app:
47+
image: myapp
48+
depends_on:
49+
- database
50+
```
51+
52+
Notice the dedicated `provider` attribute in the `database` service.
53+
This attribute specifies that the service is managed by a provider and lets you define options specific to that provider type.
54+
55+
The `depends_on` attribute in the `app` service specifies that it depends on the `database` service.
56+
This means that the `database` service will be started before the `app` service, allowing the provider information
57+
to be injected into the `app` service.
58+
59+
## How it works
60+
61+
During the `docker compose up` command execution, Compose identifies services relying on providers and works with them to provision
62+
the requested capabilities. The provider then populates Compose model with information about how to access the provisioned resource.
63+
64+
This information is passed to services that declare a dependency on the provider service, typically through environment
65+
variables. The naming convention for these variables is:
66+
67+
```env
68+
<<PROVIDER_SERVICE_NAME>>_<<VARIABLE_NAME>>
69+
```
70+
71+
For example, if your provider service is named `database`, your application service might receive environment variables like:
72+
73+
- `DATABASE_URL` with the URL to access the provisioned resource
74+
- `DATABASE_TOKEN` with an authentication token
75+
- Other provider-specific variables
76+
77+
Your application can then use these environment variables to interact with the provisioned resource.
78+
79+
## Provider types
80+
81+
The `type` field in a provider service references the name of either:
82+
83+
1. A Docker CLI plugin (e.g., `docker-model`)
84+
2. A binary available in the user's PATH
85+
86+
When Compose encounters a provider service, it looks for a plugin or binary with the specified name to handle the provisioning of the requested capability.
87+
88+
For example, if you specify `type: model`, Compose will look for a Docker CLI plugin named `docker-model` or a binary named `model` in the PATH.
89+
90+
```yaml
91+
services:
92+
ai-runner:
93+
provider:
94+
type: model # Looks for docker-model plugin or model binary
95+
options:
96+
model: ai/example-model
97+
```
98+
99+
The plugin or binary is responsible for:
100+
101+
1. Interpreting the options provided in the provider service
102+
2. Provisioning the requested capability
103+
3. Returning information about how to access the provisioned resource
104+
105+
This information is then passed to dependent services as environment variables.
106+
107+
## Benefits of using provider services
108+
109+
Using provider services in your Compose applications offers several benefits:
110+
111+
1. Simplified configuration: You don't need to manually configure and manage platform capabilities
112+
2. Declarative approach: You can declare all your application's dependencies in one place
113+
3. Consistent workflow: You use the same Compose commands to manage your entire application, including platform capabilities
114+
115+
## Creating your own provider
116+
117+
If you want to create your own provider to extend Compose with custom capabilities, you can implement a Compose plugin that registers provider types.
118+
119+
For detailed information on how to create and implement your own provider, refer to the [Compose Extensions documentation](https://github.com/docker/compose/blob/main/docs/extension.md).
120+
This guide explains the extension mechanism that allows you to add new provider types to Compose.
121+
122+
## Reference
123+
124+
- [Docker Model Runner documentation](/manuals/ai/model-runner.md)
125+
- [Compose Extensions documentation](https://github.com/docker/compose/blob/main/docs/extension.md)

‎data/summary.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,8 @@ Compose model runner:
109109
requires: Docker Compose [2.35.0](/manuals/compose/releases/release-notes.md#2300) and later, and Docker Desktop 4.41 and later
110110
Compose OCI artifact:
111111
requires: Docker Compose [2.34.0](/manuals/compose/releases/release-notes.md#2340) and later
112+
Compose provider services:
113+
requires: Docker Compose [2.36.0](/manuals/compose/releases/release-notes.md) and later
112114
Compose replace file:
113115
requires: Docker Compose [2.24.4](/manuals/compose/releases/release-notes.md#2244) and later
114116
Compose required:

0 commit comments

Comments
 (0)