score-compose

score-compose is a reference implementation of the Score specification for Docker compose. It is primarily designed for local development.

It provides a resource provisioning system that allows you to supply and customize the dynamic configuration of attached services, such as databases, queues, storage, and other network or storage APIs, by translating Score resource definitions into Docker Compose configurations.

score-compose supports most aspects of the Score specification, but certain features are validated without being applied because they do not map cleanly to the Docker Compose specification. These limitations do not impact workload execution.

Score allows you to define multiple containers within a single Workload. When using score-compose, these containers are placed within the same network namespace (similar to Kubernetes).

Important: Listening ports for containers within the same workload must not overlap.

apiVersion: score.dev/v1b1

metadata:
  name: hello-world

containers:
  first:
    image: "nginx:latest"
    variables:
      NGINX_PORT: "8080"
  second:
    image: "nginx:latest"
    variables:
      NGINX_PORT: "8081"

By default, the route resource uses a Prefix matching type, meaning a path like / will match any request path (e.g., /any/request/path).

To restrict routing to an exact match only, add the following annotation to your route resource: compose.score.dev/route-provisioner-path-type: Exact.

By default, resources in score-compose are independent. To share a single stateful resource (like a Redis instance or a database) across multiple workloads, assign the same id to the resource definition in each workload. This id must be unique to the project but identical across the workloads that need to share it.

Use the placeholder syntax ${resources.<resource-name>.<output-key>} to access resource outputs. If an output key contains a dot, escape it with a backslash: ${resources.cache-a.some\.key}.

apiVersion: score.dev/v1b1
metadata:
  name: workload-one
resources:
  cache-a:
    type: redis
    id: main-cache

---
apiVersion: score.dev/v1b1
metadata:
  name: workload-two
resources:
  cache-b:
    type: redis
    id: main-cache
  cache-c:
    type: redis

Patching templates allow you to perform post-processing on the generated Docker Compose file. You provide one or more template files via the --patch-templates flag during score-compose init.

Template Requirements:

• Templates are evaluated as Golang text/templates.
• They must output a YAML or JSON encoded array of patches.
• Each patch object must contain:
  • op: Either set or delete.
  • patch: A dot-separated JSON path to the target field.
  • value: Required if op is set.
  • description (optional): A string to be shown in the logs.

When provisioning an amqp resource, score-compose provides several output fields that can be used to construct a connection string. The available outputs are:

• host
• port
• vhost
• username
• password

You can assemble these into a standard URI format: amqp://${resources.<resource_name>.username}:${resources.<resource_name>.password}@${resources.<resource_name>.host}:${resources.<resource_name>.port}/${resources.<resource_name>.vhost}.

amqp://${resources.bus.username}:${resources.bus.password}@${resources.bus.host}:${resources.bus.port}/${resources.bus.vhost}

You can include multiple Score workloads in the same project directory. Each workload must have a unique name in its metadata.name field.

When score-compose generates a compose file for multiple workloads:

1. Containers from the same workload share a network namespace.
2. Containers from different workloads run in different network namespaces.

# Workload 1
apiVersion: score.dev/v1b1
metadata:
  name: hello-world
containers:
  first:
    image: "nginx:latest"

# Workload 2 (in a separate file like score2.yaml)
---
apiVersion: score.dev/v1b1
metadata:
  name: hello-world-2
containers:
  first:
    image: "nginx:latest"

To access the RabbitMQ broker and its management UI from your local machine, use the compose.score.dev/publish-port and compose.score.dev/publish-management-port annotations in your resource metadata.

It is recommended to apply these annotations via an --overrides-file rather than modifying your primary Score file. When using these ports, the default guest/guest credentials will be available for debugging.

resources:
  bus:
    type: amqp
    metadata:
      annotations:
        "compose.score.dev/publish-port": "5672"
        "compose.score.dev/publish-management-port": "15672"