Installing Kuzzle

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


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


sudo sysctl -w vm.max_map_count=262144
docker-compose up

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


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:


# 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:


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

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

Useful commands list


# 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


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


Get Kuzzle source code

Create the Kuzzle root directory


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

Create a directory for Kuzzle and install it


cd ~/kuzzle
git clone
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 )

Create a directory for Kuzzle Back Office and install it.

Setup PM2

Install pm2


sudo npm install -g pm2

Create a pm2 configuration file


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

Run Kuzzle via pm2 and show the logs:


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

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


# 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

Unless you're running external services locally (i.e. Elasticsearch and Redis), you'll need to configure their host and port to allow Kuzzle to reach them, in the .kuzzlerc file.

Please refer to the Kuzzle configuration section for more information.

Useful commands list


# Displaying Kuzzle logs:
pm2 logs

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

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