Docker Compose Plugin for formae

Manage Docker Compose stacks as infrastructure with formae.

This plugin provisions and manages Docker Compose projects by shelling out to the docker compose CLI. It supports the full resource lifecycle: create, read, update, delete, and discovery.

Supported Resources

Resource Type	Description
DOCKER::Compose::Stack	A Docker Compose project managed via docker compose up/down

Target Configuration

The plugin connects to a Docker daemon. The default configuration uses the local Docker socket:

new formae.Target {
  label = "local-docker"
  namespace = "DOCKER"
  config = new compose.Config {}
}

The compose.Config class exposes:

Field	Default	Description
host	unix:///var/run/docker.sock	Docker host URI

Docker credentials (registry auth, TLS certs) are read from the environment, not from the target config.

Schema Fields

The compose.Stack resource has the following fields:

Field	Type	Mutable	Description
projectName	String	No (createOnly)	Compose project name, used as native ID. Changing triggers replacement.
composeFile	String	Yes	Compose YAML content. Changes trigger docker compose up.
endpoints	Mapping<String, String>?	Yes	Named endpoint declarations (name -> service:port). Resolved to actual URLs after apply.
status	String?	Read-only	Current project status from Docker.

Resolvable

A compose.Stack exposes a StackResolvable for cross-plugin references:

local myStack: compose.Stack = ...
// Reference from another resource:
myStack.res.endpoints    // resolves to the endpoints mapping
myStack.res.projectName  // resolves to the project name

Examples

Basic

A single nginx container:

formae apply --mode reconcile --watch examples/basic/main.pkl

See examples/basic/main.pkl.

LGTM Observability Stack

Grafana LGTM all-in-one (Loki, Grafana, Tempo, Mimir) with OpenTelemetry collector:

formae apply --mode reconcile --watch examples/lgtm/main.pkl

See examples/lgtm/main.pkl.

Licensing

Licensed under FSL-1.1-ALv2. See LICENSE.