Microbase (from scratch) – getting started


This tutorial gets you up and running with Microbase from scratch. This includes downloading and compiling the source code as well as installing required 3rd party dependencies. If you’d like an easier installation method, please refer to the Microbase (from EC2) – getting started guide instead (requires you to have a Amazon Web Services account).

Requirements & Dependencies

  • A machine running a recent version of Debian or Ubuntu. Microbase and Entanglement also work on other Linux distributions, Mac OSX and Windows, but this tutorial contains instructions specifically for Ubuntu.
  • CouchDB installation (1.4 or 1.5)
  • Git
  • Java 8 (JDK if you’re going to compile from scratch)
  • Maven
  • An IRC server (for example, IRCd-hybrid)

To install all of the required dependencies, execute the following command with superuser privileges:

Verify that the CouchDB server is running

After installing CouchDB, attempt a connection to its user interface by pointing a Web browser to the following link:

Create a new administrator account (see the link in the bottom-right – which will either be ‘Fix this’ or ‘Setup more admins’), and remember the password you set. For this tutorial, we will use the username ‘microbase’ and password ‘microbase’.

Next, click the Configuration link from the Tools menu. Scroll down to the os_process_timeout option, and increase it, depending on your hardware capabilities. Start by making this value 10-100x larger than the default of 5000 (ms), which seems to have fixed CouchDB view building problems for us.

If you need the CouchDB server to be accessible from any machine other than the one you’ve just installed it on, then you’ll need to enable binding to multiple IP addresses. The simplest (and least secure) option is to allow connections from anywhere on the network. We will set this option here for convenience, but be aware of the security implications. You should probably configure a suitable firewall.

Find the configuration option bind_address under the httpd category, and set the value to (shown below):

Finally, return to the overview screen and create a new database accessible by the user account you just created:

Once created, click the Security link at the top, and add the CouchDB user you created to the list of names. Remember to surround the username in double-quote marks, as shown:

Then click Update. CouchDB is now sufficiently configured to be used with Microbase/Entanglement.

It may be worth restarting CouchDB after making the configuration changes outlined above.

Configuring ircd-hybrid

If you already have access to an IRC server, then you can skip this step. Just be sure to disable flood protection, since the default protection on some servers is as low as 5 lines.

The default Microbase (and Entanglement) user interface makes use of IRC as a distributed collaborative command-driven environment. If you don’t have one already, you will need to install an IRC server. Here, we explain how to install and configure the ircd-hybrid server, but any other IRC server software should also be suitable.

Importantly, it is necessary to disable the ‘flood protection’ feature present in many server implementations; Microbase and Entanglement processes frequently post large volumes of information to a chat channel, which may be mis-interpreted by some servers as a malicious attempt at flooding the network.

The following changes must be made to the default IRCd-hybrid configuration file.

Configure a server password and disable flood protection

Locate the first ‘auth’ block of the configuration file: /etc/ircd-hybrid/ircd.conf

Update the ‘auth’ block based on our example below. Be sure to comment out or delete any remaining ‘auth’ blocks in the configuration file.

Important lines:


Increase various IRCd-hybrid buffer sizes 

Both the Microbase and Entanglement IRC clients occasionally send “large” amounts of text. To ensure that your IRC server doesn’t ‘kick’ the clients out of the chat channel, certain default limits need to be increased. Search through the configuration file for various buffer size configuration information. Here are some examples, with suggested limits:

  • sendq = 2048kbytes;
  • number_per_ip = 20;
  • max_local = 20;
  • max_number = 500;
  • recvq = 8000 bytes;

The configuration file documents each of the listed settings. Please refer to the IRCd-hybrid documentation for further information.

Allow IRCd-hybrid to listen to more than ‘localhost’

Locate the following snippet of configuration file (listen section), and ensure that the ‘host’ line is

host = *;


Once you’ve performed the above configuration file changes, restart the server with the following command:

Acquire and build the Microbase source code

Run the following commands to clone the appropriate Git repository and configure Git to point to the latest development branch:

(Alternatively, you can clone just the develop branch if you don’t have git flow installed.)

Then, build Microbase:

The first build may take several minutes since Maven needs to download all required dependencies.

Congratulations. You should now have all the required dependencies installed and configured.