updateDockerCompose

Update the Docker Compose configuration for a CVM

updateDockerCompose

PATCH /cvms/{cvmId}/docker-compose

Updates the Docker Compose file for a running CVM. The request body is sent as text/yaml.

This function uses a two-phase flow for CVMs with on-chain KMS:

1. Phase 1: Call with the new docker_compose_file. If the CVM uses on-chain KMS, the API returns precondition_required with a compose_hash.
2. Register on-chain: Call addComposeHash to register the new compose hash on the blockchain.
3. Phase 2: Retry the call with the original YAML plus compose_hash and transaction_hash.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
docker_compose_file	string	Yes	New Docker Compose YAML content
compose_hash	string	No	Compose hash (Phase 2, sent via X-Compose-Hash header)
transaction_hash	string	No	On-chain transaction hash (Phase 2, sent via X-Transaction-Hash header)

Returns: Union of two possible responses:

Success (in_progress):

Field	Type	Description
status	"in_progress"	Update accepted
message	string	Status message
correlation_id	string	Tracking ID

Precondition required (precondition_required):

Field	Type	Description
status	"precondition_required"	On-chain registration needed
message	string	Instructions
compose_hash	string	Hash to register on-chain
app_id	string	App ID for contract interaction
device_id	string	Device ID
kms_info	KmsInfo	KMS details for chain interaction

Example — PHALA KMS:

const result = await client.updateDockerCompose({
  id: "my-app",
  docker_compose_file: newComposeYaml,
});
// result.status === "in_progress"

Example — On-chain KMS (two phases):

import { addComposeHash } from "@phala/cloud";

// Phase 1
const result = await client.updateDockerCompose({
  id: "my-app",
  docker_compose_file: newComposeYaml,
});

if (result.status === "precondition_required") {
  // Register on-chain
  const receipt = await addComposeHash({
    chain: result.kms_info.chain,
    kmsContractAddress: result.kms_info.kms_contract_address,
    appId: result.app_id as `0x${string}`,
    composeHash: result.compose_hash,
    privateKey: privateKey,
  });

  // Phase 2
  await client.updateDockerCompose({
    id: "my-app",
    docker_compose_file: newComposeYaml,
    compose_hash: result.compose_hash,
    transaction_hash: receipt.transactionHash,
  });
}

---

safeUpdateDockerCompose

Safe variant that returns a SafeResult instead of throwing on errors.