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.
Introduction
MckoiDDB is intended to be run over a cluster of machines in a network, however you may also run a setup with just one machine and no network. This type of installation is a good way for a developer to experiment with the software and find out 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 setup of a MckoiDDB installation on your local machine.
Step 1: Define a network password
MckoiDDB is intended to be run on a network where every machine runs a daemon/service called 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 and by clients of the MckoiDDB system. Every Mckoi Machine Node must share a common network password. This password ensures that if multiple MckoiDDB systems are installed on a network that they are not able to accidentally communicate with each other and thus potentially pollute each others data.
Before the Mckoi Machine Node application is started, set the network password by opening node.conf in an editor and change the network_password value to a string of your choosing. The node.conf file defines some other properties too but you can ignore them for this demonstration.
Step 2: Define the machines in the network
Every Mckoi Machine Node must know about the location of every other node in the network and who is allowed to access the network. This network schema is defined by the network.conf file. When running MckoiDDB in a network, you would ensure that the IP address and port of all the nodes are added to this file by updating the network_nodelist and connect_whitelist property values. connect_whitelist is a list of all the machines allowed to connect to the network and must include the IP address of all the Mckoi Machine Nodes and all the clients you want to allow to connect. 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 localhost, the network.conf properties should be set as follows;
# Only allow localhost connections to this node. connect_whitelist=127.0.0.1 # We are running 1 node on port 3500 of localhost. network_nodelist=127.0.0.1:3500
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 127.0.0.1 -port 3500
If you are installing multiple MckoiDDB nodes on a network, the -host argument would be the IP address of the interface on the installation machine you wish to bind the node on (for example, it might be something like 192.168.0.10 on a private network).
Step 4: Define the 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 here. For this guide, I will briefly outline these roles by saying that a MckoiDDB network must have a Manager server, at least one Root server, and at least one Block server (but preferably at least three Block servers). To assign these machine roles you will need to access the administration console. You may access the console either by using the 'console [network password]' script or by running the following Java command;
java -cp ..\..\lib\mckoiddb.jar com.mckoi.runtime.AdminConsole -netpassword [the network password]
For our localhost installation, the following commands should be entered in the administration console to define a valid network;
start role manager on 127.0.0.1:3500 start role root on 127.0.0.1:3500 start role block on 127.0.0.1:3500
For this demonstration, the above commands are assigning all three roles to the localhost node. If you were running MckoiDDB over a cluster of machines you would assign the 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 initially you will only need one Root server.
Step 5: Write your database application
The installation is complete. You will now be able to use one of the client APIs to connect to your MckoiDDB installation. The Developing a Simple Database Guide is a good place to learn about the Simple Database client API.