Blog

Introduction

One constraint with MarkLogic is that you cannot install more than one instance on a given machine. Either MarkLogic is installed or not on the machine, but you cannot install a second one. The biggest drawback with that approach is when time has come to evaluate a new version. Especially with the Early Access program, when you have access to beta versions before they are officially released. Of course you do not want to upgrade your instance to a beta version, without any testing, even if it is on your laptop or dev box.

The obvious solution that comes to mind is to create a virtual machine, for the only purpose of installing MarkLogic on it. Fortunately, MarkLogic supports CentOS, an open-source and free operating system, very similar to Red Hat. Thanks to CentOS and to help I received from an internal mailing list at MarkLogic, I was able to create such a vitrual box and use it to install MarkLogic 8 EA 2.

Disclaimer: Installing MarkLogic on CentOS, even though it is very similar to RedHat, is not supported officially. The steps presented in this blog entry are convenient if you want to create one or several virtual boxes to host different MarkLogic instances, for evaluation or development purposes. But bear in mind that this is not a supported approach, and therefore should never been used for anything else that playing around with MarkLogic, for any reason.

Note: If you use Mac OS X, and want to be able to switch between different versions of MarkLogic without using any virtual machine, have a look at this wonderful tool from Matt Pileggi: mlvm.

The ingredients

Before starting cooking the virtual box, let us get all the ingredients. You need:

Virtual Box: go to http://virtualbox.org, follow the downloads link and download the corresponding package or installer for your platform.
CentOS: got to the CentOS alternative downloads page at http://wiki.centos.org/Download, and click on the x86_64 link for CentOS version 6.5 (I could not make the version 7 work). In the next page, select any proxy server (in your own country is better), then eventually select the one image file ending in *-Minimal.iso. E.g., as of today, the latest minimal image file is CentOS-6.5-x86_64-minimal.iso, corresponding to the minimal disk image for CentOS 6.5, for the Intel 64 bits processors.
MarkLogic: download the RPM package for MarkLogic (available for Red Hat platforms), the usual way. For the Early Access program, go to http://ea.marklogic.com/.

Now that you have all the ingredients, let's start cooking!

The box

First, you need to install Virtual Box. Just follow the instructions for your platform. Once in Virtual Box, click on the button "New". Give a name to the box, e.g. "marklogic-ea", and choose the type "Linux", and version "Red Hat (64 bit)". In the next screen, chose the memory to allocate to the virtual box. The more the better, but on my laptop, I found that 2 GB was enough for simple tests. You can put more if you can afford it.

In the next screen, keep the default setting, "Create a virtual hard drive now", and continue. Then keep the default again, "VDI (VirtualBox Disk Image)", and again keep "Dynamically allocated". In the next screen, you have to set the disk size. It depends of course on the space available on your physical machine, and on what you plan to do with your MarkLogic instance. If you do not plan to make any data intensive tests, 16 or 32 GB should be enough. Fortunately, the space is dynamically allocated, so you will not waste any space you do not actually use. Then keep the default name for the HD file, and continue.

The box is now created. Before starting it, select it on the left hand-side panel in the Virtual Box Manager window, then double-click on Network. Go to the tab Adapter 2 and enable it (tick the box Enable Network Adapter). Select Host-only Adapter in the drop-down list for Attached to. And click OK.

You can now start the machine (select it on the left-hand side panel, and click start). Virtual Box will ask you to select the disk image to boot on. Browse your filesystem and select the CentOS ISO image file you downloaded. If ever Virual Box does not ask you for an image file, stop the machine, select it on the left hand-side panel, and double-click on "Storage". Add a new CD/DVD device to the IDE controller, and choose the disk image.

The OS

Your brand new virtual machine is now booting on the CentOS install disk. You will now follow the CentOS installer to install an OS on your machine. In the menu, select Install or update.

Note that starting from there, the mouse and keyboard can be captured by the virtual machine. Even Alt-Tab on Windows and Linux and Cmd-Tab on Mac, used to switch between applications, do not work. This is very annoying. In order for the host OS to get control back, you must hit the Host key, which is indicated in the bottom-right corner (by default, it is the left Cmd key on Mac, only the one on the left of the space bar).

For the storage, select Basic Storage Devices (it is the default option). You can safely discard any data on your (virtual) disk. For the network, click on Configure Network, edit both eth0 and eth1 and for each of them tick the box Connect automatically (if you do not see eth1, double-check that you have enabled the Host-only Adapter above). Make sure you Use All Space and write changes to disk. You can now reboot.

Log in as root, using the password you just set up in the installer. Execute ifconfig, and write down the IP of your machine (in the eth1 section, line inet). In my case, this is 192.168.56.101. From your host machine, open a terminal, and ping your machine with ping 192.168.56.101, to see if it responds. You can also connect remotely with ssh root@192.168.56.101. For now on, you can log out from the console on the virtual box, let it run in the background, and connect from your host terminal via SSH (which integrates better with your host OS, e.g. let you use copy and paste).

Note that if ssh says WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!, it is becasue the RSA key has changed for the same IP. This happends if you threw away a virtual box and installed a new one. It might reuse the same IP, but it is a new machine, with a new certificate. This is normal and might be ignored (well, not exactly; to be able to use ssh, you need to open ~/.ssh/known_hosts and remove the line corresponding to the IP of the virtual machine).

Then update your system. The following commands will open all ports (this is a dev box, remember), update the packages in your system, and install the packages needed to install and run MarkLogic:

[root@ea ~]# /etc/init.d/iptables save
[root@ea ~]# /etc/init.d/iptables stop
[root@ea ~]# chkconfig iptables off
[root@ea ~]# yum update
[root@ea ~]# yum install gcc
[root@ea ~]# yum install kernel-devel
[root@ea ~]# halt # reboot
[root@ea ~]# yum groupinstall 'Development Tools'
[root@ea ~]# yum install gdb glibc glibc.i686 lsb

And voilà! Your virtual machine is ready to install MarkLogic...

MarkLogic

First, you have to copy the MarkLogic RPM package from the host terminal to your virtual box. Note: do not forget the colon character (the ':') at the end of the IP address:

$ scp MarkLogic-8.0-20140626.x86_64.rpm root@192.168.56.101:

Then to install MarkLogic itself, this is very simple. Execute both following commands from the guest system (that is, through SSH):

[root@ea ~]# rpm -i MarkLogic-8.0-20140626.x86_64.rpm 
[root@ea ~]# /etc/init.d/MarkLogic start

MarkLogic should now be installed and running. You can confirm it by going to http://192.168.56.101:8001/. You should see the admin console, asking you a few more questions to finish the install process. But starting here, the rest is a traditional MarkLogic story...

A very last point though. I usually add a mapping to the file /etc/hosts (on the host system), with a line like `192.168.56.101 mlea`. With such a line, you can then use the following URL for instance to access the MarkLogic admin interface on your virtual box: http://mlea:8001/.

Enjoy, and use wisely!

Posted by Florent Georges, on 2014-09-06T18:44:00, tag: marklogic.