Getting started

In this tutorial you will learn in a few steps how to launch Kuzzle and how to interact with it by persisting data and being notified when data is updated.

Running Kuzzle automagically

In this section, we'll learn how to launch Kuzzle the quick way, i.e. via the installation script.

Grab a console and launch the following command

#!/bin/bash

sudo bash -c "$(curl http://get.kuzzle.io/)"

This command downloads and executes the installation script with root privileges. The script checks the system for a set of pre-requisites. If necessary, it installs Docker and Docker-compose, then runs Kuzzle.

Once the installation process is complete, the script will greet you with the following message

# [✔] Kuzzle is running!

Your Kuzzle server is now ready to be used. To check it, you can hit the main HTTP API endpoint by browsing the page http://localhost:7512?pretty=true or via cURL on the command line:

#!/bin/bash

curl "http://localhost:7512/?pretty=true"

Kuzzle will respond you with a list of the existing routes.

Where do we go from here?

Now that Kuzzle is running on your computer, you can dive into playing with it by:

SDK play time

It's time to play with the Kuzzle SDK. In this section, we will persist a document and subscribe to notifications in Kuzzle using the JS SDK.

Before proceeding, ensure that your system matches the following requisites:

  • A fairly recent version of NodeJS (i.e. v6+) should be installed on your system (instructions here),
  • A Kuzzle server up and running.

Prepare your environment

Create your playground directory and install the Javascript SDK from the command line using npm:

#!/bin/bash

mkdir "kuzzle-playground"
cd "kuzzle-playground"
npm install kuzzle-sdk

Then, create a init.js file and start coding:

const Kuzzle = require('kuzzle-sdk')

// connect to the Kuzzle server
const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

kuzzle
  .createIndexPromise('playground')
  .then(() => kuzzle.collection('mycollection').createPromise())
  .then(() => {
    console.log('playground/mycollection ready')
  })  
  .catch(err => {
    console.error(err.message)
  })  
  .finally(() => kuzzle.disconnect())

This code does the following:

  • loads the Kuzzle SDK from its NPM package,
  • creates an instance of the SDK and connects it to the Kuzzle Backoffice running on localhost (and selects the playground as default index),
  • creates the playground index,
  • creates the mycollection collection (within the playground index),
  • disconnect from Kuzzle to end the script.

Run your file in NodeJS

#!/bin/bash

node init.js

You're now ready to say Hello to the World!

Create your first "Hello World" document

Create a create.js file with following code:

const Kuzzle = require('kuzzle-sdk')

// connect to the Kuzzle server
const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

// get message from command line arguments
const message = {message: process.argv[2]}

kuzzle.collection('mycollection')
  .createDocumentPromise(message)
  .then(res => {
    console.log('the following document has been successfully created:\n', message)
  })
  .catch(err => {
    console.error(err.message)
  })
  .finally(() => kuzzle.disconnect())

This code does the following:

  • creates a new document containing a message saying "Hello, World" in mycollection within the playground index,
  • logs a success message to the console if everything went fine,
  • logs an error message if any of the previous actions failed,
  • disconnect from Kuzzle to end the script.

Run your file in NodeJS

#!/bin/bash

node create.js 'Hello, World'

You can find more resources about Kuzzle SDK in the SDK Documentation.

Subscribe to data changes (pub/sub)

Kuzzle provides pub/sub features that allow you to be notified in real-time on the state of your data (check the Room Class Documentation for a deep-dive on notifications).

Let's get started. Open a new termnial in the playground directory you created before and create the subscribe.js file containing the following code:

const Kuzzle = require('kuzzle-sdk')

// connect to the Kuzzle server
const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

// create a reference to the data collection
const collection = kuzzle.collection('mycollection')

// define a filter
const filter = {
    exists: {
        field: 'message'
    }
}

// create a subscription on the collection matching given filters
collection.subscribe(filter, (error, result) => {
    // this function is called each time kuzzle notifies us with a document matching our filters
    console.log('message received from kuzzle:', result)
})

Run your file in NodeJS

#!/bin/bash

node subscribe.js

And let it wait for documents entering the scope of the filter.

Now, get back to the previous terminal window and execute once more the create.js script. Take a look at the output of the subscribe.js script. You will see that, each time a document with a message field is persisted in Kuzzle, a notification is shown as standard output.

Where do we go from here?

Now that you are started and operational with Kuzzle, you can fully leverage its power by: