Compose Converter

The Compose migration path should help users move Compose intent into MacTain Blueprints. The source-backed target model is a Blueprint TOML file that MacTain can validate, resolve, plan, and start.

Command Reference

Command	Description	Typical use
`mactain blueprint convert compose --input <compose.yaml> --output <blueprint.toml>`	Converts Docker Compose YAML into a Blueprint file.	Create the first MacTain version of a Compose workflow.
`mactain blueprint validate <blueprint.toml>`	Validates the converted Blueprint.	Catch unsupported or invalid fields before runtime changes.
`mactain blueprint resolve <blueprint.toml>`	Shows the resolved MacTain model.	Review variables, profiles, images, mounts, ports, and labels.
`mactain blueprint plan <blueprint.toml>`	Previews create/start work.	Review operational changes before starting the app.
`mactain blueprint start <blueprint.toml>`	Starts the converted Blueprint.	Run the migrated workflow after validation and planning.

Defaults And Behavior

Compose conversion produces a MacTain Blueprint TOML file.
--vars-values-file can provide interpolation values for ${VAR}.
--import-compose-file-secrets must be explicit when importing supported top-level Compose file secrets.
--map-compose-external-secret <compose>=<mactain> maps an external Compose secret to an existing MacTain secret.
Compose labels can come from labels and deploy.labels; direct labels override deploy.labels on conflicts.
blueprint resolve does not print canonical Docker Compose YAML.

Migration Shape

Identify the services, images, ports, environment variables, and storage in the Compose file.
Map those concepts into a MacTain Blueprint.
Validate the Blueprint.
Resolve or plan the Blueprint before starting it.

mactain blueprint validate ./myapp.toml
mactain blueprint resolve ./myapp.toml --json
mactain blueprint plan ./myapp.toml

Important Boundary

blueprint resolve is the MacTain-native equivalent of inspecting the structured model MacTain understands after defaults and profile selection. It does not print Docker-compatible canonical Compose YAML.

Practical Use Cases

Use case: migrate one Compose service at a time

Use this when a Compose file has multiple services and you want to reduce unknowns. Start with one service, map its image and ports, then validate the Blueprint.

mactain blueprint validate ./myapp.toml
mactain blueprint plan ./myapp.toml

After the first service works, add volumes, networks, and dependent services in small steps.

Use case: inspect profile-specific output

Use this when your Compose workflow has dev-only or prod-only services and you map them to Blueprint profiles.

mactain blueprint resolve ./myapp.toml --profile dev --json
mactain blueprint start ./myapp.toml --profile dev

Use case: compare a Docker workflow to MacTain concepts

Use this when you are not sure whether a Compose setting maps to networking, volumes, or container flags.

mactain container start --help
mactain blueprint docs

Troubleshooting Entry Points

Unsupported Compose field: simplify the source file and map the behavior to a Blueprint concept.
Port does not respond: review Networking.
Data is not retained: review Volumes.

Next Steps

After validating the Blueprint, review Blueprints and then Networking before starting the full workflow.