Compose Resources

All Compose resources are exported from @intentius/chant-lexicon-docker. The export variable name becomes the key in the output section.

Each constructor’s props are typed from the Compose spec (ServiceProps, VolumeProps, NetworkProps, DockerConfigProps, DockerSecretProps), so your editor completes the fields and a misspelled field or a wrong value type is a compile error. A string field also takes an env() value, or another entity, which is written as its name.

Service

Maps to services.<name> in docker-compose.yml.

import { Service, env } from "@intentius/chant-lexicon-docker";

export const api = new Service({
  image: "myapp:1.0",
  ports: ["8080:8080"],
  environment: {
    NODE_ENV: "production",
    DB_URL: env("DATABASE_URL", { required: true }),
  },
  depends_on: ["db"],
  restart: "unless-stopped",
  healthcheck: {
    test: ["CMD", "curl", "-f", "http://localhost:8080/health"],
    interval: "30s",
    timeout: "10s",
    retries: 3,
  },
  deploy: {
    replicas: 2,
    resources: {
      limits: { cpus: "0.5", memory: "512M" },
    },
  },
});

Volume

Maps to volumes.<name> in docker-compose.yml.

import { Volume } from "@intentius/chant-lexicon-docker";

// Named volume (default driver)
export const pgdata = new Volume({});

// Custom driver options (e.g. NFS)
export const nfsdata = new Volume({
  driver: "local",
  driver_opts: {
    type: "nfs",
    o: "addr=192.168.1.1,rw",
    device: ":/path/to/share",
  },
});

// External volume (pre-existing)
export const shared = new Volume({ external: true });

Network

Maps to networks.<name> in docker-compose.yml.

import { Network } from "@intentius/chant-lexicon-docker";

export const backend = new Network({ driver: "bridge" });

export const frontend = new Network({
  driver: "overlay",
  attachable: true,
});

Attach a service to named networks:

export const api = new Service({
  image: "myapp:1.0",
  networks: ["frontend", "backend"],
});

DockerConfig

Maps to configs.<name> in docker-compose.yml. Used for non-sensitive configuration files.

import { DockerConfig } from "@intentius/chant-lexicon-docker";

export const nginxConf = new DockerConfig({ file: "./nginx.conf" });

Mount it in a service:

export const proxy = new Service({
  image: "nginx:alpine",
  configs: [{ source: "nginxConf", target: "/etc/nginx/nginx.conf" }],
});

A config can carry its content inline instead of pointing at a file, and a service can name it by the declared value. The value serializes as the config’s Compose key.

import { DockerConfig, Service } from "@intentius/chant-lexicon-docker";

export const appConf = new DockerConfig({ content: "log_level: info\n" });

export const app = new Service({
  image: "my-app:1.4.2",
  configs: [{ source: appConf, target: "/etc/app/config.yaml" }],
});

DockerSecret

Maps to secrets.<name> in docker-compose.yml. For sensitive values.

import { DockerSecret } from "@intentius/chant-lexicon-docker";

// File-backed
export const dbPassword = new DockerSecret({ file: "./secrets/db_password.txt" });

// External (managed outside Compose)
export const apiKey = new DockerSecret({ external: true });

Mount in a service:

export const api = new Service({
  image: "myapp:1.0",
  secrets: ["dbPassword", "apiKey"],
});

Keys that are not identifiers

The export name is the key in docker-compose.yml. For a key that cannot be an export name, such as db-password, set it with composeKey. A reference to the entity writes the key:

import { DockerSecret, Service, composeKey } from "@intentius/chant-lexicon-docker";

export const dbPassword = composeKey("db-password", new DockerSecret({ file: "./secrets/db_password.txt" }));

export const api = new Service({
  image: "myapp:1.0",
  secrets: [dbPassword], // written as db-password
});

Two entities of the same kind cannot take one key; the build stops with an error that names both.

Telemetry attribution

Inside a workspace, the docker lexicon adds two variables to every service’s environment so that its spans name the declaration that produced them (#2558, ws-060).

services:
  appService:
    environment:
      OTEL_SERVICE_NAME: appService
      OTEL_RESOURCE_ATTRIBUTES: chant.workspace=reference,chant.member=delivery,chant.decl=appService${CHANT_RELEASE_ATTRIBUTES:-}

OTEL_SERVICE_NAME is the service’s key. OTEL_RESOURCE_ATTRIBUTES lists chant.workspace, chant.member, chant.decl (the service’s key, which is its node id in chant workspace graph without the member prefix) and, when the build has an environment from --env or ownership.env, deployment.environment.name. A service whose image is pinned by digest (image@sha256:...) also gets service.version. A value the service already sets is kept, and only the missing attributes are added. The value ends with ${CHANT_RELEASE_ATTRIBUTES:-}: a release deploy through chant run --components sets CHANT_RELEASE_ATTRIBUTES in the environment of docker compose up, adding service.version and vcs.ref.head.revision, and any other up leaves it empty, so the Compose file does not change with a release (ws-081).

A project with no chant.workspace.json is unchanged. It can opt in with telemetry.attribution: true in chant.config.ts, which stamps the attributes that need no workspace, and inside a workspace telemetry.attribution: false turns it off. How a reader joins a span to a member lists what each attribute joins to.