Specmate operations

For a pull-only install and upgrades, start with Install. See the Compose breakdown before choosing development/preview files.

Specmate uses Bun 1.4.2 for dependency management and builds, and Node 24 for the production web application and JavaScript workers. PostgreSQL is required. A private S3-compatible bucket is needed for uploads and build artifacts; application startup does not require storage configuration. Email supports passwordless sign-in. An ERP or external webhook receiver is optional. The approved application profile is recorded in .project/config.json; the capability catalog describes additional reusable modules, not features enabled in this application.

Local application

  1. Reproduce dependencies with bun install --frozen-lockfile.
  2. Configure a disposable development database, passwordless email delivery, private storage, and application URL using .env.example. Never reuse production targets. For browser File UI uploads, the configured S3 endpoint must be reachable by both the application and browser, with narrowly configured CORS.
  3. Apply committed migrations with bun run db:migrate and bun run jobs:migrate.
  4. Run bun run dev. Sign in and open Designs. Create a synthetic proving project explicitly: this is illustrative engineering data, not a qualified hardware design.
  5. Explore assembly instances and cable documents. Freeze definitions before pinning them in another revision; changes and upgrades require explicit new revisions.
  6. Publish the synthetic specification, evaluate a choice, and review its reasons and provenance. A synthetic fact is not a verified measurement of the selected hardware.

Build the production application with docker build -t specmate-local:mvp .. The image uses the existing Node startup, migration, queue, and health infrastructure. The core uses AGPL-3.0-only; see LICENSING.md. Before publishing an image, review its exact dependency/runtime/asset obligations and authorize a publishing destination.

Native CAD worker

The web process and ordinary queue worker exclude engineering.cad. Run one separately isolated worker with explicit SPECMATE_NATIVE_RUNNER=1, the same development database and private bucket, and a reviewed native tool installation. The production image contains .output/specmate-cad-worker.mjs, .output/cad-assets, and license notices. The dedicated worker executes under Node, with Linux bubblewrap and prlimit boundaries; the native tool environment must supply KiCad, Python, and the configured OpenSCAD tool root. No native tools or container socket are exposed to web requests.

Select exact board and shell revisions and queue a build. Each attempt records source hashes, inputs, toolchain, logs, native artifacts, and checks. Interrupted jobs recover through the existing queue lease/retry mechanism; cancellation accepts no partial build. Review successful electrical/topology/mesh checks and unresolved physical checks before creating an immutable review release. Downloading a portable JSON package checks every included artifact's byte count, hash, ancestry, and authorized rights.

The bounded original recipe generates a passive two-contact PCB and a parametric shell. It does not convert arbitrary imported CAD into arbitrary hardware. Imported originals are preserved; an editable derivative is a separate artifact. Unknown rights block release. Generated CAD, clean ERC/DRC, and mesh validity do not establish physical fit, printability, electrical performance, or bench validation.

API and integrations

Manage engineering API keys through the existing hashed credential lifecycle. /api/openapi.json describes the versioned /api/v1/engineering operations. Read/write permissions and current workspace authorization are both required. Legacy project-only keys do not gain engineering access. Immutable releases remain retrievable after later project edits; revision impact includes historical release roots.

Optional release webhooks use the signed, durable delivery contract. Configure only a trusted server-side scope/target; credentials and target URLs never enter queued event payloads. Consumers must verify raw bytes and deduplicate stable event IDs before applying effects. The application works with no external receiver configured.

Engineering limits

Physical qualification remains unknown. FDM/resin slicing, printer submission, firmware, richer geometry analysis and runtime extensions are not implemented by the current engineering workflow. Fabrication, flashing and machine operation require separate explicit scope. See docs/ENGINEERING-WORKFLOWS.md for the supported flow.

Native worker command

After building the production image, a deployment can run its dedicated bundle as node .output/specmate-cad-worker.mjs in a reviewed native-tool environment. Set SPECMATE_NATIVE_RUNNER=1, the shared application database/queue and private storage settings, SPECMATE_CAD_SOURCE_ROOT to the deployed recipe assets, and SPECMATE_OPENSCAD_ROOT to the reviewed native runtime. The web app and ordinary worker cannot execute CAD. See workers/cad/README.md for exact isolation and toolchain requirements. Configure these settings in a private deployment environment, never in browser requests or committed files.

Shutdown and persistence

docker compose down stops the application stack and retains database volumes. Do not add --volumes when retaining project data. Back up both database metadata and referenced private object bytes; validate their identities, hashes and permissions in a separate restore target before relying on a backup. Migrations are explicit, never an implicit application startup step.