This guide uses the public Stackdome demo repository, a three-service application with a Next.js web resource, a background worker, Redis, and persistent data.
Clone it and run stackdome init beside its Compose file:
The initializer creates stackfile.yaml; use that generated file as your starting point instead of writing one from memory. When a Compose file is present, treat it as architectural evidence for the Stackfile: service topology, images and builds, ports, environment, commands, dependencies, and volumes. The initializer attempts an experimental conversion; when there is no Compose file, it creates a starter Stackfile named after the current directory.
Convert a Compose file
stackdome init checks the repository root for these files, in order:
Specify a different Compose file with:
The conversion writes stackfile.yaml, lists the resources and volumes it found, and validates the result. Read every warning before continuing. In particular:
- A local Compose build does not identify a Git repository. Set
build.repo to the repository URL.
- A service without an image or build configuration needs one before it can deploy.
- A Compose
env_file is reported as a warning. Add its path as env_file under the converted resource if the deployment should load it.
The converter may write the file even when the generated configuration does not pass validation. Treat the generated file as a draft and correct every reported problem.
Docker Compose conversion is experimental. Use the Compose file as a reference for creating the Stackfile and treat converted output only as scaffolding, not a deployment-ready translation. Compose build contexts such as ./web are relative to the local Compose file and do not identify a Git repository. Stackdome builds from a cloned repository, so every converted build needs a build.repo, and its context must be rewritten relative to that repository’s root. Other Compose behavior may also require manual translation; inspect the source files and validate the result before deploying.
stackdome validate. The validated Stackfile is the deployment contract.
stackdome init refuses to replace an existing stackfile.yaml. Review the file before using --force, which overwrites it.
Complete the demo Stackfile
The demo’s Compose file gives the initializer the three resources, Redis command, environment values, dependencies, port 3000, and /data volume mount. Its ./web and ./worker build contexts are local paths, so the generated file warns that both resources need build.repo. Because the Git clone starts at the repository root, those contexts also need to become hello-stack/web and hello-stack/worker.
Use the repository as the build source and change the contexts from local ./web and ./worker paths to paths relative to the Git repository root. Replace Compose substitutions with the application’s documented defaults, declare Redis’s private TCP port, and use Stackdome output references for the public URL and Redis hostname:
web and worker build different contexts from the same repository. redis uses a published image and stays private. Both application resources receive Redis’s deployment hostname through {{ redis.host }} rather than assuming that a Compose service name will resolve. The named volume preserves Redis’s append-only data under /data.
Use the Stackfile reference when you add build settings, environment variables, secrets, addons, dependencies, or storage.
Validate before deploying
Run validation after every edit:
To validate a file at another path, use the flag reported by the installed CLI:
Do not deploy until validation succeeds. If this guide and the installed release candidate disagree, stackdome validate is the authority for that CLI version.