Getting Started

In this tutorial you will learn how to install, run and use Kuzzle in just a few steps. We will walk you through creating an app that can store documents in Kuzzle and generate a notification for each new document.

Running Kuzzle

In this section we'll learn how to quickly get Kuzzle up and running using our installation script.

Open a terminal and run the following command:

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

This command downloads and executes the installation script using root privileges. The script checks the system for a set of prerequisites and installs any necessary tools, like Docker or Docker Compose. When the installation is complete it will automatically run Kuzzle.

This command downloads, installs and runs Kuzzle.

Use the --no-run option to prevent the script from running Kuzzle.

Once the installation process is complete, you will see the following message:

# Kuzzle is now running

Your Kuzzle is now running! To test it, you can explore the main HTTP API by clicking this link or by using cURL on the command line:

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

If everything is working you should see a JSON document that contains a list of API endpoints.

Helper scripts for systemd

If you want to run Kuzzle automatically at startup there are a few scripts that help you do this with systemd.

If you want to run Kuzzle automatically at startup there are a few scripts in $PWD/kuzzle/script/ that help you do this with systemd:

  • Run the add-kuzzle-boot-systemd.sh as root to add a service inside /etc/systemd/system that will start Kuzzle on boot.
  • Run the remove-kuzzle-boot-systemd.sh as root to remove the service so that Kuzzle won't start on boot.

What now?

Now that Kuzzle is up and running, you can start playing around with it:

Fun with SDKs

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

Before proceeding, please make sure your system has these programs installed:

Prepare your environment

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

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

Then, create an init.js file and start by adding the code below. This will load the Kuzzle Javascript SDK:

const Kuzzle = require('kuzzle-sdk')

Next we will instantiate a client that will automatically connect to Kuzzle via websockets. If Kuzzle is not running on localhost, replace it with the corresponding server name or ip address. Here we also specify 'playground' as the default index that the client will query:

const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

Next we will add a listener to detect if there is a problem with our connection to Kuzzle:

kuzzle.on("networkError",function(error){
  console.error("Network Error:"+error);
})

Finally, we will add the code that will access Kuzzle to create a new index 'playground' and a new collection 'mycollection' that we will use to store data later on.

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

Your init.js file should now look like this:

// load the Kuzzle SDK module
const Kuzzle = require('kuzzle-sdk')

// instantiate a Kuzzle client, this will automatically connect to the Kuzzle server
const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

// add a listener to detect any connection problems
kuzzle.on("networkError",function(error){
  console.error("Network Error:"+error);
})

// create a 'playground' index and then a collection named 'mycollection' that we can use to store data
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 Kuzzle running on localhost (and selects the playground as default index),
  • creates the playground index,
  • creates the mycollection collection (within the playground index),
  • disconnects from Kuzzle after the collection is created or if an error occurs.

Run your file in Node.js

node init.js

Your console should output the following message:

playground/mycollection ready

Create your first "Hello World" document

Create a create.js file with following code:

// load the Kuzzle SDK module
const Kuzzle = require('kuzzle-sdk')

// instantiate a Kuzzle client, this will automatically connect to the Kuzzle server
const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

// create an object that contains the message we want to store
const message = {message: "Hello, World!"}

// create a document in the 'mycollection' collection
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 the message "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,
  • disconnects from Kuzzle after the document is created or if an error occurs.

Run your file in Node.js

node create.js

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

Subscribe to data changes (pub/sub)

Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the Room class definition in the SDK Reference).

Let's get started. Create a subscribe.js file with following code:

// load the Kuzzle SDK module
const Kuzzle = require('kuzzle-sdk')

// instantiate a Kuzzle client, this will automatically connect to the Kuzzle server
const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})

// create a reference to the 'mycollection' 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 Node.js

node subscribe.js

Your subscribe.js app is now running and monitoring any documents that match the filter, specifically documents that have a message field.

Now in another terminal, launch the create.js file that we created in the previous section.

node create.js

This will create a new document in Kuzzle which will trigger a notification in the subscribe.js app. Check the subscribe.js terminal to make sure a new log appears every time a document is created using the create.js app:

message received from kuzzle: { status: 200,
  requestId: '02042a18-927b-43a1-98e3-e1637e2a1447',
  timestamp: 1515590928775,
  ...}

Where do we go from here?

Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: