Getting started

This guide runs Specmate locally for evaluation and development. Use a disposable local database and test identity. Do not point a local checkout at production services or data.

Requirements

• Git, Docker with Compose, Bun 1.4.2 (the pinned tooling version), and Node.js 24 LTS.
• A sign-in method: GitHub OAuth, a configured OIDC provider, or local magic-link email through Mailpit.

Install and run

From the repository root:

bun install --frozen-lockfile
cp .env.example .env
docker compose up -d postgres

Edit .env and set a long random BETTER_AUTH_SECRET and APP_BASE_URL=http://localhost:3000. The example database URL matches the default local Compose PostgreSQL credentials. Configure either GitHub OAuth (GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET) or OIDC (OIDC_DISCOVERY_URL, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET) for sign-in.

For local email sign-in, start the local-only Mailpit sink in another terminal:

bun run email:dev:mailpit

Mailpit's inbox is at http://127.0.0.1:8025. Set MAGIC_LINK_ENABLED=true, SMTP_HOST=127.0.0.1, SMTP_PORT=1025, SMTP_SECURITY=opportunistic, and EMAIL_FROM_ADDRESS=specmate@example.test in .env; leave SMTP credentials empty. Mailpit captures mail locally and does not forward it.

Apply the app and queue migrations, then start the development server:

bun run db:migrate
bun run jobs:migrate
bun run dev

Start the ordinary queue worker in another terminal from the same repository root:

bun run jobs:worker

This is the local development worker command. Production workers execute the built Node bundle. The ordinary worker does not run native CAD jobs.

Open http://localhost:3000, sign in, and go to Designs (/app/designs). Choose Create synthetic demo to explore a two-device example with reusable boards, a shell, and an interconnect. This explicitly creates public synthetic values under your signed-in account; it does not import a real design or validate hardware.

Stop the development database with docker compose down. Stop Mailpit with bun run email:dev:down if you started it. These commands keep the local Compose data volume unless you explicitly remove it.

Use the engineering workspace

Start with Engineering Workflows for projects, shared definitions, exact revisions, configuration, CAD build evidence, releases, and the engineering API. The native CAD worker is a separate, opt-in setup; it is not started by bun run dev or the ordinary queue worker.

Production image

The production app and JavaScript workers run on Node. Build locally with docker build -t specmate:local .; the root Compose stack builds and runs the app, migrations, PostgreSQL, and ordinary queue worker. Configure a real authentication provider, private storage, secrets, and mail delivery before using it beyond local evaluation. See .env.example for supported server-side settings and Licensing before distributing an image.

Troubleshooting

• If the app cannot connect to PostgreSQL, check that the local postgres service is healthy and .env uses the matching host port and credentials.
• If sign-in is unavailable, verify that one provider is configured. For magic links, confirm Mailpit is running and the SMTP settings above match.
• If a file upload is unavailable, configure private S3-compatible storage. Browser uploads require an endpoint reachable by the browser and correctly scoped CORS; storage is optional until used.
• If port 3000 or 5432 is occupied, change APP_PORT or POSTGRES_PORT for Compose, and update APP_BASE_URL/DATABASE_URL as needed. The Vite dev server uses port 3000; change its command if that port is occupied.