RegisterSign In

Quick Start Guide

If you haven't done so already, you should download MckoiDDB first.

If you already have a network and wish to dive straight into a network installation, or if you are looking for a more detailed description of the installation process, go to the MckoiDDB Network Guide.


MckoiDDB is intended to be run over a cluster of machines in a network, however you may also create an installation with just one machine and no network. This type of installation is a good way for a developer to experiment with the software and discover how it works. The downloaded distribution includes all the scripts and configuration files for this guide in the demo/single/ directory. This document guides you through the installation of MckoiDDB on your local machine.

Step 1: Define a network password

MckoiDDB is intended to be run on a network where each machine runs the MckoiDDB software as a daemon/service which we call a Mckoi Machine Node. A Mckoi Machine Node is a server application that listens on a TCP/IP port for requests made by other Machine Nodes on the network, and by clients of the MckoiDDB system. Every Mckoi Machine Node on a network must share a common network password. This password ensures that if multiple MckoiDDB systems are installed on a network that they are not accidentally configured to communicate with each other and thus potentially pollute each others data.

Before the Mckoi Machine Node application is started, you must set the network password by opening the node.conf file in an editor and changing the network_password value to a password of your choosing. The node.conf file defines some other properties but they can be ignored for now.

Step 2: Define the machines in the network

A Mckoi Machine Node must be told of the location of every other machine node available on the network and the IP address of the database clients that are permitted to access the network. This network schema is defined in the network.conf file. When running MckoiDDB on a network, you must ensure that the IP address and port of all the machine nodes are added to the network_nodelist and connect_whitelist properties in this file. connect_whitelist must include the IP address of all the Mckoi Machine Nodes and all the clients you want to allow to use the network. The network_nodelist property is a list of the IP/port addresses of all the Mckoi Machine Nodes on the network.

For our single node installation on your local machine, the network.conf properties should be set as follows;

# Only allow localhost connections to this node.


# We are running 1 node on port 3500 of localhost.


This tells MckoiDDB that the local machine will be connecting to the machine node, and that the only machine node currently available is on port 3500 of the local machine.

Step 3: Start the node

Now the configuration is complete you can start the node by either running the 'start_node' script or with the following Java command (assuming you are running from the demo/simple directory);

java -cp ..\..\lib\mckoiddb.jar com.mckoi.runtime.MckoiMachineNode -host -port 3500

If you are installing MckoiDDB nodes on a network, the -host argument in the above command should be set to the IP of the network interface you wish to bind the node on (for example, it might be something like on a private network).

Step 4: Define the machine node roles

A Mckoi Machine Node may perform up to three different roles as part of the operation of the whole network. The machine roles are covered in more detail in the Network Guide. For this introductory guide however, it is suffice to explain that a MckoiDDB network must have a minimum of one Manager server, one Root server, and one Block server (but preferably at least three Block servers). Each machine node may provide one of each of these roles. To assign these machine roles you will need to use the administration console. The administration console is accessed either by using the 'console [network password]' script provided in the installation, or by running the following Java command;

java -cp ..\..\lib\mckoiddb.jar com.mckoi.runtime.AdminConsole -netpassword [the network password]

For the local installation we are setting up in this article, the following commands should be entered in the administration console;

start role manager on
start role root on
start role block on

In this demonstration, the above commands will assign all three roles to the local machine node. If you were running MckoiDDB over a cluster of machines you would assign the different roles to separate machines in the network. In a networked setup, you should assign as many machines as you have to be the Block server role as these machines will be the repositories of data in the network. You may only assign one server to the Manager role and you should assign one or more Root servers. It is preferable to have 2 to 3 root servers to start out in a network installation.

Step 5: Develop your database application

The installation is now complete. You will now be able to use one of the client APIs to set up a data model and connect to your MckoiDDB installation. The Developing a Simple Database Guide is a good place to continue from here.

The text on this page is licensed under the Creative Commons Attribution 3.0 License. Java is a registered trademark of Oracle and/or its affiliates.
Mckoi is Copyright © 2000 - 2019 Diehl and Associates, Inc. All rights reserved.