Installing Kuzzle

In this section, we'll see how to install Kuzzle via Docker and Docker-compose and manually.

Docker

Before launching Kuzzle, ensure that your system matches the following pre-requisites:

Get the standard docker-compose.yml file, copy it into a directory and start Kuzzle:

In this case, you need to increase the maximum virtual memory allowed by typing

#!/bin/bash

sudo sysctl -w vm.max_map_count=262144
wget http://kuzzle.io/docker-compose.yml
docker-compose up

To persist this changes add this line to your /etc/sysctl.conf

#!/bin/bash

echo "vm.max_map_count=262144" >> /etc/sysctl.conf

Your terminal will show the log messages of Kuzzle's components starting. After only a few seconds, you should see the following ready message appear:

#!/bin/bash

# kuzzle_1         | [✔] Kuzzle server ready

Your Kuzzle server is now ready to be used. For instance, you can hit the main HTTP API endpoint by browsing the page http://localhost:7512 or via cURL on the command line:

#!/bin/bash

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

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

Useful commands list

#!/bin/bash

# Updating docker images used by Kuzzle:  
docker-compose -f "<docker-compose-file.yml>" pull

# Showing Kuzzle logs:  
docker exec -ti "<container name>" pm2 logs

# Restarting Kuzzle:
docker exec -ti "<container name>" pm2 restart all

# Stopping Kuzzle:
docker exec -ti "<container name>" pm2 stop all

# Starting Kuzzle:
docker exec -ti "<container name>" pm2 start all

# Accessing Kuzzle CLI:
docker exec -ti "<container name>" bin/kuzzle -h

Manually

In this section we will cover the manual installation on Linux systems, since this is the environment all the components of the Kuzzle stack work natively in.

We will run the Kuzzle stack using pm2, from the current user home directory.

Supported operating systems

The following operating systems are actively supported (64-bit versions only):

  • Ubuntu: 14.04 and 16.04
  • Debian: 7 and 8

Prerequisites

  • A Elasticsearch version 5.0 instance or upper running on localhost:9200.
  • A Redis version 3.x instance running on localhost:6379 (preferred version: v3.2).
  • NodeJS version 6.x or upper.
  • Python version 2.7 preferred.
  • a C++11 compatible compiler.
  • GDB version 7.7 or upper.

Get Kuzzle source code

Create the Kuzzle root directory

#!/bin/bash

mkdir -p "~/kuzzle"
cd "~/kuzzle"

Create a directory for Kuzzle and install it

#!/bin/bash

cd ~/kuzzle
git clone https://github.com/kuzzleio/kuzzle.git
cd kuzzle
npm install

# init submodules to install defaults kuzzle plugins
git submodule init
git submodule update

# install dependencies for all enabled plugins
for PLUGIN in ./plugins/enabled/*; do
  if [ -d "${PLUGIN}" ]; then
    ( cd "${PLUGIN}" && npm install )
  fi
done

Create a directory for Kuzzle Back Office and install it.


Setup PM2

Install pm2

#!/bin/bash

sudo npm install -g pm2

Create a pm2 configuration file

#!/bin/bash

echo "apps:
   - name: kuzzle
     cwd: ${KUZZLE_CORE_INSTALL_DIR}
     script: ${KUZZLE_CORE_INSTALL_DIR}/bin/kuzzle
     args: start
     env:
       NODE_ENV: production
  " > ~/kuzzle/pm2.conf.yml

Run Kuzzle via pm2 and show the logs:

#!/bin/bash

pm2 start ~/kuzzle/pm2.conf.yml
pm2 logs

After only a few seconds, you will see the following ready message appear:

#!/bin/bash

# kuzzle_1         | [✔] Kuzzle server ready

The Kuzzle Back-office can be reached on http://localhost:3000.
Kuzzle HTTP API can be reached on http://localhost:7512/
Socket IO and Websocket channels can be reached over the HTTP server, on port 7512.

Change external services hosts or ports

If you are running some of the service(s) externally, you can configure their host and port using some environment variables and/or a .kuzzlerc file.

Please refer to the Kuzzle configuration section for more information.

Useful commands list

#!/bin/bash

# howing Kuzzle logs:
pm2 logs

# Starting, restarting or stopping Kuzzle core :
pm2 "<start|stop|restart>" KuzzleServer

# Starting, restarting or stopping Kuzzle core :  
pm2 "<start|stop|restart>" KuzzleProxy

# Accessing Kuzzle CLI
~/kuzzle/bin/kuzzle -h