Guides v2.x

Run Kuzzle #

Kuzzle is a Node.js application that can be installed on a large number of environments.

It only requires two services: Elasticsearch (opens new window) and Redis (opens new window).

In this guide we will use Docker and Docker Compose to run those services.

Prerequisites #

It's recommanded to use Node Version Manager to avoid rights problems when using Node.js and dependencies. You can install NVM with the one-liner script documented on NVM Github repository (opens new window)

Throughout this guide, we will need to use Kourou (opens new window), the Kuzzle CLI.

You can install Kourou globally by using NPM: npm install -g kourou

Kuzzle uses compiled C++ dependencies so a compile toolchain (a C++ compiler like g++ or clang, make and python) is necessary to run npm install kuzzle. For the sake of simplicity we will use a Docker and Docker Compose throughout this guide.

If you encounter issues about permissions when trying to use Docker, please follow the Docker as a non root user guide (opens new window).

Let's go! #

First, we will initialize a new application using Kourou:

Copied to clipboard!
kourou app:scaffold playground

  🚀 Kourou - Scaffolds a new Kuzzle application

  ✔ Creating "playground/" directory
  ✔ Creating and rendering application files
  ✔ Installing latest Kuzzle version via NPM and Docker (this can take some time)

 [] Scaffolding complete! Use "npm run dev:docker" to run your application

This will create the following files and directories:

Copied to clipboard!
├── lib                  < application code
├── .eslintignore
├── .gitignore
├── .eslintrc-ts.json
├── .eslintrc.json
├── app.ts               < application entrypoint
├── docker-compose.yml   < Docker Compose configuration
├── ergol.config.json
├── package.json
├── Dockerfile
└── tsconfig.json

The app.ts file contain the basic code to run a Kuzzle application. This file is meant to be executed with Node.js as any application.

Copied to clipboard!
import { Backend } from "kuzzle";

const app = new Backend("playground");

  .then(() => {"Application started");

We can now run our first application with npm run dev:docker

Under the hood, the command npm run dev:docker uses nodemon (opens new window) and ts-node (opens new window) inside the Docker container to run the application.

Now visit http://localhost:7512 (opens new window) with your browser. You should see the result of the server:info action.

Admin Console #

We can also use the Admin Console (opens new window) which allows to manage your data, your users and your rights.

The Admin Console is a Single Page Application (opens new window) written in Vue.js and using the Javascript SDK. No data related to your connection to Kuzzle will pass through our servers.

First, we need to setup a new connection to a Kuzzle application. Open the Admin Console (opens new window) in your browser and then fill the form as follow:

Admin Console create connection form

Click on Create Connection and then select your connection on the dropdown menu.

When asked for credentials, just choose Login as Anonymous.

You are now connected to your local Kuzzle application with the Admin Console! Everything is empty but we are gonna change that in the next section.

The minimum rights required by an user to connect to the Kuzzle Admin Console are:

Copied to clipboard!
  "controllers": {
    "auth": {
      "actions": {
        "login": true,
        "checkToken": true,
        "getCurrentUser": true,
        "getMyRights": true