KlausSchaefers/quant-ux: self-hosted prototyping and usability testing

What Quant-UX is, and the problem it targets

Quant-UX describes itself as a research, usability and prototyping tool: you build a prototype, run it past testers, and get back data you can analyse. The repository you are looking at is the front end only. The README is explicit about this split: "Quant-UX has two components. A front-end (this package) and a backend (qux-java)." That sentence is the most important thing on the page, because it tells you the shape of every installation problem you will hit.

The audience is teams that want to run usability studies on their own infrastructure rather than through a hosted service. The README points at a working demo at quant-ux.com, so you can look at the interface before deciding anything. The package name is quant-ux, the version in package.json is 5.0.25, and the primary language is Vue. The licence is GPL-3.0.

There is an obvious mismatch worth naming. A prototyping tool competes for the same attention as general design software, but Quant-UX's differentiator is the testing loop: prototypes exist to be measured. If you only want to draw screens, the extra services (Mongo, mail, websocket) are pure overhead.

The four-service architecture behind the front end

The Compose file in the README defines four services. qux-fe is the Vue application, served by the mini web server that ships in the server/ directory of this repository. qux-be is the Java backend image. mongo is a stock Mongo image with a volume mounted at /data/db. qux-ws is a websocket server used for live collaboration or live study sessions.

The front end does not talk to the backend directly by default. It proxies. QUX_PROXY_URL on qux-fe points at the backend, and the README notes the front end "comes with it's own mini web server, which also include a proxy that redirects all request to the correct backend." That is why the front end exposes port 8082 while the backend listens on 8080 internally.

The websocket server is the piece most likely to be misconfigured, because it is addressed from the browser, not from inside the Compose network. The README sets QUX_WS_URL=ws://127.0.0.1:8086 and adds the comment "change to where the websocket server is deployed for external access." If you leave that at localhost and your users are remote, the socket will fail for them while the rest of the app appears fine.

On the backend, QUX_HTTP_HOST is described as "the URL included in the mails, e.g. password resets." So password reset links are built from that value. Get it wrong and users receive links pointing at a container hostname they cannot reach.

Installing Quant-UX with Docker Compose

The README calls the prebuilt Docker images "the easiest way to get your own installation up and running," and points to a separate repository by Brian McGonagill (bmcgonag/quant-ux-docker) for instructions. The manual route below is the Compose file printed in the README, trimmed to the parts you must change.

Start by writing docker-compose.yaml. The front end needs a proxy target, an auth mode, and a websocket URL that browsers can reach:

services:
  qux-fe:
    image: klausenschaefersinho/quant-ux
    environment:
      - QUX_PROXY_URL=http://quant-ux-backend:8080
      - QUX_AUTH=qux
      - QUX_WS_URL=ws://127.0.0.1:8086
    ports:
      - 8082:8082

The backend carries the settings that decide whether the instance is usable and safe. QUX_JWT_PASSWORD must be replaced; the README says to "update QUX_JWT_PASSWORD the ENV variable to make sure your installation is secure." Mail settings matter too, since signup and password resets depend on SMTP:

  qux-be:
    image: klausenschaefersinho/quant-ux-backend
    environment:
      - QUX_MONGO_CONNECTION_STRING=mongodb://quant-ux-mongo:27017
      - QUX_MAIL_HOST=mail.example.com
      - [email protected]
      - QUX_MAIL_PASSWORD=sTr0ngPa55w0Rd
      - QUX_JWT_PASSWORD=some-long-string-of-mix-case-chars-and-nums
      - QUX_USER_ALLOW_SIGNUP=true
      - QUX_USER_ALLOWED_DOMAINS=*

QUX_USER_ALLOWED_DOMAINS is a comma separated list of domains, or * for all. Tighten it before you expose the instance. Then bring everything up:

make up

The Makefile rule runs docker compose --file docker/docker-compose.yml up. The README's own instruction is the equivalent docker compose up. Either way, you should see the four containers start, and the app should answer on port 8082.

If you would rather develop against the source, the repository expects Node.js and npm. The README's prerequisite is npm install, followed by npm run serve for a hot-reloading dev server, npm run build for a production bundle, npm run test:unit for unit tests and npm run lint for linting. The Dockerfile also defines a runtime-development target that runs npm run serve -- --port 8082, built with make build-dev.

AI features and the cost they introduce

The backend accepts QUX_AI_TOKEN, described in the README as "Your open ai token that is shared with all users," alongside QUX_AI_ALLOWED_URLS=https://api.openai.com/v1/. The word shared is doing a lot of work in that sentence.

The README does not soften this: "Please be aware that this can lead to significant costs. Best create a token with a limited budget." That is a configuration where every user of your instance spends against one credential. If you run an open signup instance with QUX_USER_ALLOW_SIGNUP=true and QUX_USER_ALLOWED_DOMAINS=*, you have combined an open door with a shared paid credential. The README gives you the two switches to prevent that; it does not enforce any of them for you.

If you do not need the AI assistance, leaving QUX_AI_TOKEN unset is the simplest way to keep the instance predictable. Nothing in the README suggests the rest of the tool depends on it.

Where a self-hosted Quant-UX installation gets painful

The front-end repository is not a complete product, and the README says so without much ceremony. The backend lives in a separate repository, KlausSchaefers/qux-java. Its prerequisites are listed as MongoDB (> 4.4), Java (1.8) and a mail server. Java 1.8 is old, and the README does not describe an upgrade path for it. If your organisation has moved past 8, you are running the backend on a legacy runtime or not at all.

Mail is a hard dependency rather than a nice-to-have. The README's manual section lists an SMTP server among the backend's requirements, and QUX_HTTP_HOST exists specifically so that reset links point somewhere real. A fresh install without working SMTP will look broken at the first signup or password reset.

The websocket service is a fourth moving part with its own image and its own environment variables (QUX_SERVER, QUX_SERVER_PORT=8086). The README does not document what degrades when it is unavailable, so treat a missing socket as an unknown rather than a graceful fallback.

Finally, the front end is Vue 2, and package.json pins vue ^2.6.14 with vue-router ^3.5.1 and vue-i18n ^8.10.0. That is a stack you inherit, not one you choose. Anyone who wants to extend the front end is writing Vue 2 options-API code, and the README offers no migration story. There is also no release history in the repository metadata, so version tracking is done through package.json rather than changelogs.

Quant-UX against Figma and Penpot

The honest comparison is not feature-for-feature. Figma and Penpot are design tools; Quant-UX is a testing instrument that happens to include a prototype editor. If your goal is a shared design file that engineers inspect, Figma or Penpot is the right shape of tool, and Quant-UX's Compose stack is a cost you would pay for nothing.

The difference that matters is where the data lives and what happens after the prototype is finished. Figma and Penpot are hosted products (Penpot can also be self-hosted). Quant-UX expects you to run the whole stack yourself: Mongo for storage, a Java backend, SMTP for account mail, and a websocket server for live sessions. In exchange, study data stays on your infrastructure and there is no per-seat design licence.

That trade is only worth it if you actually run studies. If you do not, the maintenance burden of four containers and a legacy Java runtime is strictly worse than a browser tab.

Licence and the cost of staying current

Quant-UX is GPL-3.0. If you deploy it internally, that is largely a non-issue. If you intend to modify the front end and ship it as part of a product, GPL-3.0 has obligations that differ from permissive licences, and the repository's LICENSE file is the document that governs. This is a description of the licence identifier, not legal advice; talk to someone qualified before building a commercial derivative.

Upgrade cost is dominated by the backend, which is not in this repository. The front end is a Vue CLI 5 project: npm run build produces a dist/ directory, and the Dockerfile copies dist/, server/ and public/ into the runtime image. A front-end upgrade is therefore a rebuild, and the Makefile gives you build-prod for that. The backend image tag is unpinned in the README's Compose file (klausenschaefersinho/quant-ux-backend with no version), so a pull can move you forward without warning. Pin the image digests yourself if you care about reproducible deploys. The README does not document a rollback procedure for either component.

Editorial conclusion

Adopt Quant-UX if you want a self-hosted place to build prototypes and collect study data, and you have someone comfortable running Docker Compose, MongoDB, SMTP and a Java backend. Do not adopt it if you want a managed SaaS tool, or if you expect the front-end repository alone to give you a working system. Before committing, verify that the backend image klausenschaefersinho/quant-ux-backend and the websocket image klausenschaefersinho/quant-ux-websocket start cleanly against your own Mongo instance, and set QUX_JWT_PASSWORD to a real secret rather than the sample string.

Frequently asked questions

Official sources

1. Issues
2. KlausSchaefers/quant-ux on GitHub
3. License: GPL-3.0
4. README