Quick start

In five minutes you’ll have the full stack running locally, a published questionnaire, an embedded form on a plain HTML page, and a response sitting in a MongoDB you own.

What you need

• Docker with Compose (Docker Desktop on Windows/macOS works fine)
• Node.js 18+ — for the seed script and for building the embed bundle
• git

1. Start the stack

git clone https://github.com/JoshuaLeoSmith/forms-engine.git
cd forms-engine
docker compose up --build

The first build takes a few minutes. When it settles you have four services:

Service	URL
Editor	http://localhost:8081
Backend API	http://localhost:8080 (OpenAPI UI at /swagger-ui.html)
MongoDB	mongodb://localhost:27017/forms_engine
MinIO console	http://localhost:9001 (login minioadmin / minioadmin)

The backend checks its file storage with a write/read/delete round-trip at startup and refuses to start if storage is misconfigured — so if the backend container is up, uploads work.

2. Create and publish a questionnaire

Open the editor at http://localhost:8081, create a questionnaire, add a step with a couple of questions, and click Publish changes. That creates immutable version 1 and gives the questionnaire a public id (visible in the editor’s Embed panel).

Or skip the clicking — seed a ready-made demo questionnaire:

node examples/seed/seed.mjs

The script imports and publishes a small demo (a text question, a yes/no toggle, and a dessert question that only appears when you answer yes — so you see a visibility rule working immediately) and prints its publicId:

Imported and published "Demo Questionnaire" (live = v1).

  publicId: q_xxxxxxxxxx

3. Embed it in a plain HTML page

The repo ships a minimal example page. Build the embed bundle once, then point the example at your questionnaire:

npm install
npm run build

Open examples/plain-html/index.html and paste your publicId into the public-id attribute:

<script type="module" src="../../packages/renderer/dist/forms-engine.esm.js"></script>

<forms-engine
  public-id="PASTE_PUBLIC_ID_HERE"
  api-base="http://localhost:8080">
</forms-engine>

Serve the repo root and open the example:

npx serve .

Then visit http://localhost:3000/examples/plain-html/. The questionnaire renders; the page also logs every component event (fe-loaded, fe-screen-changed, fe-completed, …) to the browser console, so open devtools to watch the embed talk.

4. Fill it in and find the response

Answer the questions and click Finish. Then look in Mongo:

docker compose exec mongo mongosh forms_engine --eval 'db.responses.find().pretty()'

You’ll see your response: a flat answers map keyed by question code with typed values, a status of COMPLETED, and a versionNumber pinning it to the questionnaire version it was answered against.

Where to go next

• What’s in the box — what each part of the stack does
• Installation & self-hosting — running it for real: configuration, storage, geocoding, reverse proxy
• Editor guide — building real questionnaires: hierarchy, rules, publishing
• Embedding — the full web component reference, plus React and Angular wrappers