Skip to main content
An App can reference a Docker Compose file in place. The compose file stays the one definition of your services; the App document adds what Levelrail owns: project, environment, tags, domains and the values for ${VAR}.

The shape

spec.compose and spec.service are mutually exclusive. path must be relative, inside the folder you apply, with no .. and no symlink on the way. A working copy lives in examples/iac/compose-ref/.

Turn it on

The feature is beta and off by default. Enable the runtime setting iac.compose_refs:
Size caps are iac.compose_max_file_kb, iac.compose_max_files and iac.compose_max_total_kb.

Apply

levelrail-cli apply -f DIR reads the documents, finds every spec.compose.path, and sends those files as attachments next to the documents. The compose file is never parsed as a resource document. Plan first:
A compose App deploys through the compose deploy path on every apply, so no_deploy is refused (compose_no_deploy_unsupported). stack plan and stack apply send the referenced compose files like apply does, with the same size caps and the same refusal of symlinks. Dropping a compose App from the files plans a delete. Pass --confirm-destroy <stack name> to stack plan and again to stack apply (API: confirm_destroy) to allow it in that run; without it the plan carries a destroy_not_confirmed item and the CLI prints the command to re-run. --yes never implies it. Approval needs the approver to type it again.

What strict mode refuses

A referenced file comes from a repository, so it runs under a stricter parser than a file you paste into the dashboard. Every refusal has a stable code (see errors): Plan reports every refusal in one pass, with the service and key but never a value.

Import a compose project

levelrail-cli import compose-ref --reference [dir] emits one App per compose file that points at it. The compose file is never copied or rewritten, and --write DIR must be the folder that holds the compose files so every path stays relative without ...
The output is validated with the real loader and the strict parser before it is printed or written. A file strict mode would refuse is not emitted; the command prints the code for each refusal as a note. Every variable becomes a ${{ env.NAME }} placeholder, and names that look like secrets are also listed in SECRETS.md; provide each value at apply time with --allow-env NAME or --var NAME=VALUE. Values are never read. Existing files are kept without --force. The file name must look like compose.yaml or docker-compose.yml.

Adopt a running compose app

If the project already runs on Levelrail, make the file match what is deployed so the first plan is empty:
It writes the current deployed revision to the path the referencing App names, refuses to overwrite an existing file without --force, then runs a plan and tells you whether it is empty. The stored revision is the file as it was deployed, before interpolation, so no env value is written.

Limits

  • External secretRef sources in spec.compose.env are refused for now; use a literal or a ${{ env.NAME }} placeholder. ${{ secrets.NAME }} is not accepted in spec.compose.env.
  • env_file, bind mounts, build: and include are refused.
  • There is no git form (spec.compose.git) yet. Reference a file in the folder you apply.
  • A compose App is one compose project: there is no per-service selector. Use profiles for subsets.
Last modified on November 17, 2026