README.md

Mira - A Qlik Associative Engine Discovery Service

As of 1 July 2020, Qlik Core is no longer available to new customers. No further maintenance will be done in this repository.

Overview

Mira provides Qlik Associative Engine discovery in a Docker containerized environment. Mira is implemented on Node.js and supports different orchestration platforms such as Docker Swarm and Kubernetes. Mira can also operate in a simpler DNS mode and a Local mode.

The documentation in this repository is primarily intended for contributors to Mira development and for those who want to improve Mira by submitting issues.

For Mira's end-user documentation, see Qlik Core documentation site.

Contributing

Contributions are welcome and encouraged! See more info at Open Source at Qlik R&D.

Docker Image

Mira is distributed to end users as a the qlikcore/mira Docker image. Also see the Dockerfile. The version file needs to be generated before building the Docker image locally.

Running Mira as a Plain Node.js Process

For convenience and development purposes, Mira can be started as a non-Dockerized Node.js process. In this case, Mira would most commonly also be used in Local mode, so the MIRA_MODE environment variable should be provided accordingly:

$ MIRA_MODE=local npm start

Development

Editor/IDE Configuration

No particular editor or IDE is assumed. The repo root contains an .editorconfig file for editors that support it. If not, make sure that the used editor is configured accordingly.

Coding Guidelines

JavaScript code shall be developed according the Airbnb JavaScript Style Guide.

The eslintrc.json file incorporates these rules with minor modifications.

Install Packages

Once the repo has been cloned, in the repo root, run:

$ npm install

Generating version file

Mira will in run-time make use of build information e.g. commit SHA and version number. This information is already present in the Mira Docker image, but if running Mira as a non-dockerized process this file (version.json) must also be available locally. The file can be generated by running the following command:

./generate_version_file.sh

Generating the OpenAPI Specification

Mira's REST API is specified in the api-doc.yml OpenAPI document. The OpenAPI specification is generated from JSDoc by running:

$ npm run generate-openapi

Circle CI

Circle CI is configured to build a new Docker image from all pushed commits on all branches of Mira. As part of this, the built Docker image is pushed to Docker Hub. If pushing to a feature branch (different from master), the Docker image is tagged with <version>-<build-number>, where <version> is fetched from package.json, and <build-number> is the automatically increased Circle CI build number given to each build. If pushing to master the image is also tagged with latest.

Testing

Unit and component tests can be run with:

$ npm run test:unit
$ npm run test:component

These tests run Mira in isolation and does not depend on any external components.

Integration tests depend on external components. Before they can run, you must accept the Qlik Core EULA by setting the ACCEPT_EULA environment variable, you start the services by using the docker-compose.yml file:

$ ACCEPT_EULA=yes docker-compose up -d
$ npm run test:integration

To run integration tests towards a specific image tag, provide the TAG environment variable to docker-compose:

$ ACCEPT_EULA=yes TAG=:<YOUR TAG HERE> docker-compose up -d
$ npm run test:integration

See package.json for more test script variants.

Releasing

Mira service release

The helper script release.sh provides a convenient way to release a new version of the service and to automatically bump versions as needed.

Check usage information in release.sh on how to perform the release and version bumping by running:

$ release.sh -?