Q server

Developing Tools

A Q tool is a HTTP service providing an API to get rendering information for a given dataset.

Q cli

With Q cli you can easily setup new tools and test them with Q dev server which is a Q server light offering the relevant routes for rendering info.


The cli tool is an npm package and can be installed by running

$ npm install -g @nzz/q-cli


Once you’ve installed Q cli you can bootstrap a new tool by running

$ Q new-tool new-tool-name

while ‘new-tool-name’ is the name of the tool you are creating. To get a list of all available command options you can run

$ Q new-tool --help

Now you are ready to rumble, i.e. you can change the schema in /resources/schema.json and the rendering in /rendering-info/web.js. You can get an overview about the tool routes below in the section API entpoints.

To see how the rendering infomation for a tool is being displayed you can start a Q dev server by running

$ Q server

The tool itself has to be started too to be able to see anything. To get a list of all available command options you can run

$ Q server --help

Further informationen can be found on GitHub.

API Endpoints

One endpoint to return the tool specific JSON schema is mandatory as it’s used by Q editor for rendering and validation of the respective form:

Additionally you can specify an endpoint to get rendering information for a given Q item. See Rendering Info? for detailed information about what we mean with that term. The exact endpoint path is variable and specified in config/tools.js of your Q server implementation for each tool and target individually. The path may be meaningful in the sense of what will be returned. So far, we make use of the following two endpoints:

As explained in on name and path on Rendering Info? we’ll need additional endpoints if a tool requires stylesheets or scripts to load:

  module.exports = {
    method: 'GET',
    path: '/stylesheet/{name*}.css',
    handler: async function(request, h) {
      // return the stylesheet content


We deploy each tool as a Docker container in our environment. See Docker documentation to get familiar with Docker. Our Dockerfiles do have a simple structure which is the same for each tool:

# Use following version of Node as the base image
FROM node:9

# Set work directory for run/cmd

# Copy package.json into work directory and install dependencies
COPY package.json /app/package.json
RUN npm install

# Copy everthing else in work directory
COPY . /app

# Run node
CMD ["node", "/app/index.js"]

All docker containers are publicly available on Docker Hub, just search for our organization nzzonline to get the container list.

We use Rancher to host our containers. See Rancher Website or Rancher documentation for more information. You can setup your whole environment differently and without Docker of course.


Travis is our continious integration service of choice. If you want to learn how to set it up, consult the Travis documentation. The build includes execution of tests, creation and push of the docker container to docker hub as well as, if the current branch is staging, the automatic upgrade of the docker container in Rancher.

dist: trusty
sudo: true
- docker
language: node_js
- '8'
- npm install
- DOCKER_IMAGE_NAME="q-renderer-skeleton"
- npm test
- docker build -t $DOCKER_IMAGE_NAME:$DOCKER_TAG .
- echo $DOCKER_PASSWORD | docker login -u="$DOCKER_USERNAME" --password-stdin; docker tag $DOCKER_IMAGE_NAME:$DOCKER_TAG
  nzzonline/$DOCKER_IMAGE_NAME:$DOCKER_TAG; docker push nzzonline/$DOCKER_IMAGE_NAME:$DOCKER_TAG;
  - node_modules