First Steps with Kuzzle

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

This section learns you how to quickly get Kuzzle up and running using our installation script.

Open a terminal and run the following command:

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

This command downloads and executes the installation script. The script checks the system for a set of prerequisites and installs missing ones, such as Docker. When the installation is complete, it will automatically run Kuzzle.

There are also more alternative ways to install 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"

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

Congratulations! You have completed the Kuzzle installation, it will now accept requests on localhost:7512:
  • via HTTP
  • via Websocket
Having trouble?
  • Get in touch with us on Gitter! We're happy to help.
  • Try one of these alternative installation methods.

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
If you are performing a clean install you might see some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies.

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
Congratulations! You are now ready to say Hello to the World!
Having trouble? Get in touch with us on Gitter! We're happy to help.

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 have now successfully stored your first document into Kuzzle. Click here to see how you can use the Kuzzle Admin Console to browse your collection and confirm that your document was saved.
Having trouble? Get in touch with us on Gitter! We're happy to help.

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,
  ...}
Congratulations! You have just choreographed your first pub/sub pattern!
Having trouble? Get in touch with us on Gitter! We're happy to help.

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: