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 -s https://raw.githubusercontent.com/kuzzleio/kuzzle-build/master/setup.sh)"

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.

Create your first "Hello World" document

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

Save the following JS code in the new create.js file:

var Kuzzle = require('kuzzle-sdk')

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

// get a reference to the a collection
var collection = kuzzle.collection('mycollection')

// define the document itself
var document = {
    message: 'Hello, world!'
}

// persist the document into the collection
collection.createDocument(document)

Run your file in NodeJS

#!/bin/bash

node create.js

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:

var Kuzzle = require('kuzzle-sdk')

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

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

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

// create a subscription on the collection matching given filters
collection.subscribe(filter, function(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: