Which Compose file?
For a container install on another machine, use compose.install.yaml only. It pulls the Specmate image and provides a database, ordinary worker and optional local services. Follow Install or the browser YAML helper.
| File | Purpose | How to use it |
|---|---|---|
compose.install.yaml |
Pull-only install on a testing/server box. No checkout, Bun or image build required. | Download it and .env.install.example; select a published image tag/digest. Explicit migration services are in the setup profile; optional mailpit and storage profiles support private evaluation. |
compose.yaml |
Source development and CI foundation. Builds specmate:local, includes PostgreSQL, app, explicit migration services and ordinary worker. |
Run from a source checkout with its own .env. It is not needed alongside the install file. |
compose.preview.yaml |
Disposable browser/CI evaluation using one selected image and a local sign-in inbox. Its app waits for a one-shot migration service. | Use .env.preview.example and this file alone. Keep Mailpit private. This file is intended for fresh evaluation, not the documented upgrade procedure. |
compose.storage.yaml |
Standalone local S3 provider fixtures: RustFS or Garage and optional Garage UI. | Use the documented storage development scripts or explicit profiles. Its development credentials and ports are not installation defaults. |
compose.email.yaml |
Optional standalone local Mailpit sink for source development and compatibility tests. | Start separately with docker compose -f compose.email.yaml up -d. An app container needs reachable SMTP settings; localhost inside a container is that container. |
compose.cache.yaml |
Optional disposable Valkey fixture for capability tests/development. | Start explicitly. It uses memory-backed ephemeral data and is not required by Specmate's selected application profile. |
These files are alternatives or dedicated test fixtures, not a list of YAMLs to stack together. Compose merges service names and top-level project names; mixing unrelated files can replace configuration or attach a different volume. For an install, keep one file, a private .env.install, and a stable project name.
Processes and images
One ghcr.io/formless63/specmate image contains the Node application, ordinary Jobs worker, app/Jobs migration commands, storage operator commands, and a native-worker JavaScript bundle. Multiple service entries select different commands from the same image. The PostgreSQL, Mailpit and RustFS containers use their upstream images.
A bundled native-worker entry point does not supply KiCad/OpenSCAD tools or enable CAD execution. The isolated native runner requires its own reviewed tool environment and explicit opt-in; see the operator guide. The ordinary worker does not claim CAD jobs.