# About The Compose application model defines `service` as an abstraction for a computing unit managing (a subset of) application needs, which can interact with other services by relying on network(s). Docker Compose is designed to use the Docker Engine ("Moby") API to manage services as containers, but the abstraction _could_ also cover many other runtimes, typically cloud services or services natively provided by host. The Compose extensibility model has been designed to extend the `service` support to runtimes accessible through third-party tooling. # Architecture Compose extensibility relies on the `provider` attribute to select the actual binary responsible for managing the resource(s) needed to run a service. ```yaml database: provider: type: awesomecloud options: type: mysql size: 256 name: myAwesomeCloudDB ``` `provider.type` tells Compose the binary to run, which can be either: - Another Docker CLI plugin (typically, `model` to run `docker-model`) - An executable in user's `PATH` If `provider.type` doesn't resolve into any of those, Compose will report an error and interrupt the `up` command. To be a valid Compose extension, provider command *MUST* accept a `compose` command (which can be hidden) with subcommands `up` and `down`. It *MAY* additionally implement a `stop` subcommand to support `docker compose stop`, and a `pull` subcommand to take part in image distribution (see [Image distribution](#image-distribution)). Optional subcommands are declared through the provider metadata: the presence of the command block is what opts the provider in. ## Up lifecycle To execute an application's `up` lifecycle, Compose executes the provider's `compose up` command, passing the project name, service name, and additional options. The `provider.options` are translated into command line flags. For example: ```console awesomecloud compose --project-name up --type=mysql --size=256 "database" ``` > __Note:__ `project-name` _should_ be used by the provider to tag resources > set for project, so that later execution with `down` subcommand releases > all allocated resources set for the project. ## Communication with Compose Providers can interact with Compose using `stdout` as a channel, sending JSON line delimited messages. JSON messages MUST include a `type` and a `message` attribute. An unknown message type fails the command: a provider that requires a message the running Compose does not support must fail loudly rather than degrade silently. To let a provider adapt instead, Compose announces the message types it accepts in the `COMPOSE_PROVIDER_MESSAGES` environment variable of the provider process, as a comma-separated list (e.g. `error,info,setenv,rawsetenv,debug,publish-endpoint,get-service-config,get-relay-info`): check membership before emitting an optional message. ```json { "type": "info", "message": "preparing mysql ..." } ``` `type` can be either: - `info`: Reports status updates to the user. Compose will render message as the service state in the progress UI - `error`: Lets the user know something went wrong with details about the error. Compose will render the message as the reason for the service failure. - `setenv`: Lets the plugin tell Compose how dependent services can access the created resource. The variable is automatically prefixed with the service name. See next section for further details. - `rawsetenv`: Same as `setenv`, but the variable is injected as-is without the service name prefix. Useful when applications require exact variable names that cannot be altered. - `debug`: Those messages could help debugging the provider, but are not rendered to the user by default. They are rendered when Compose is started with `--verbose` flag. - `get-service-config`: Asks Compose for the resolved configuration of the service the provider manages. See next section. - `get-relay-info`: Asks Compose what address a locally-run endpoint should bind so the relay deployed for this service can reach it — Compose owns the platform knowledge, the provider just binds what is announced. Only meaningful for a provider running its service **locally**; a provider backing the service with a remote resource never needs it. See [Binding a local endpoint for the relay](#binding-a-local-endpoint-for-the-relay). - `publish-endpoint`: Declares where a network endpoint of the provider's resource is actually reachable. The message is `"=:"` — the port consumers know on the left, the real location on the right, as seen FROM THE PROVIDER'S HOST (typically a port published on the host): ```json { "type": "publish-endpoint", "message": "80=localhost:49152" } ``` TCP only; the message may be repeated, one per port. When a provider publishes at least one endpoint, Compose deploys a relay container in place of the service so that dependents reach the resource at the compose-native address — see [Compose-native addressing with `publish-endpoint`](#compose-native-addressing-with-publish-endpoint). ## Requesting the service configuration A provider can ask the running Compose process for the resolved definition of the service it manages — the exact model Compose is executing, not a re-resolution. The request is a regular JSON line on `stdout`: ```json { "type": "get-service-config" } ``` Compose answers on the provider's `stdin` with one JSON line: the resolved, canonical JSON of the service — the same shape as this service's entry in `docker compose config --format json`, after interpolation and normalization: ```json { "image": "mysql:8", "environment": { "...": "..." } } ``` There is no parameter: a provider can only obtain the definition of its own service. The message can be sent several times; each occurrence is answered with one line. Compose versions that predate this message treat it as a protocol error and abort the command, and never write anything to the provider's `stdin` (the provider reads EOF). A provider that requires the service configuration should treat EOF as "this Compose version does not support provider requests" and report an actionable error; a provider that can operate without it should simply not send the message. ```mermaid sequenceDiagram Shell->>Compose: docker compose up Compose->>Provider: compose up --project-name=xx --foo=bar "database" Provider--)Compose: json { "info": "pulling 25%" } Compose-)Shell: pulling 25% Provider--)Compose: json { "info": "pulling 50%" } Compose-)Shell: pulling 50% Provider--)Compose: json { "info": "pulling 75%" } Compose-)Shell: pulling 75% Provider--)Compose: json { "setenv": "URL=http://cloud.com/abcd:1234" } Compose-)Compose: set DATABASE_URL Provider--)Compose: json { "rawsetenv": "SECRET_KEY=xxx" } Compose-)Compose: set SECRET_KEY (as-is) Provider-)Compose: EOF (command complete) exit 0 Compose-)Shell: service started ``` ## Image distribution A provider-backed service can declare `build` or `image` like any other service; the image then has to reach the provider's runtime, which may be nowhere near the local daemon. Providers opt into image distribution by declaring a `pull` block in their `metadata` output — like `stop`, the presence of the block is the declaration of support. Providers without it keep managing images on their own during `up`. When the provider declares `pull`, Compose invokes it during the image phase of `up` (after any build) and on `docker compose pull`: ```console awesomecloud compose --project-name pull --image= --source= --policy= [--digest= --created=