MarkLogic 9 Product Documentation

Installation Guide for All Platforms — Chapter 2

Upgrading from Previous Releases

If you have previously installed MarkLogic on a machine, you must uninstall the old release before proceeding with the new installation. For information on removing the software, see Removing MarkLogic or the Installation Guide from the previous release. This section describes the following information and upgrade paths:

• Windows Service Parameters
• Upgrading from Release 9.0-1 or Later
• Upgrading from MarkLogic 7 or MarkLogic 8
• Upgrading from Release 6.0 or earlier
• Upgrading Clusters with DB Replication Configured

If you are upgrading a cluster to a new release, see Upgrading a Cluster to a New Maintenance Release of MarkLogic Server in the Scalability, Availability, and Failover Guide. The Security database and the Schemas database must be on the same host, and that host should be the first host you upgrade when upgrading a cluster.

MarkLogic Server does not support downgrades. Once you have upgraded to a later release, you cannot downgrade to your original release. To retain the option to restore to a previous version of MarkLogic Server, make a complete backup of your content and secuity databases before upgrading.

http://host:8001/security-upgrade-go.xqy?force=true

Installing MarkLogic

This section describes the procedure for installing MarkLogic Server on each platform. Perform the procedure corresponding to the platform to which you are installing.

If you are upgrading a cluster to a new release, see Upgrading a Cluster to a New Maintenance Release of MarkLogic Server in the Scalability, Availability, and Failover Guide. The Security database and the Schemas database must be on the same host, and that host should be the first host you upgrade when upgrading a cluster.

It is not recommended to install the converters while MarkLogic Server is running. The reason for this is that the server checks the converters presence and version number only upon start-up. So the server will not have accurate information about the converters in this case. The recommended installation procedure is to stop the server if it is running, install or upgrade the server, install the converters, then start the server.

The following table shows the installation directory (<marklogic-dir>) and the default data directory for each platform:

The default forest directory is the same as the default data directory if the optional data directory is not specified during forest creation. On UNIX platforms, if you want MarkLogic Server to use another location for its default data directory, make your data directory (/var/opt/MarkLogic on Linux) a soft link to the alternate location.

In MarkLogic release 9.0-4 and later, MarkLogic Converters installation directory remains the same as in previous releases, namely:

When a new node joins an existing cluster, the server does not try to figure out automatically whether the MarkLogic Converters package is needed or not. An XDMP-CVTNOTFOUND error will be thrown if converters/filters built-in functions are called on nodes that do not have MarkLogic Converters installed.

Starting MarkLogic Server

MarkLogic Server will automatically start when the computer reboots. To start MarkLogic Server without rebooting, perform the following command for the corresponding platform:

/sbin/service MarkLogic start

This starts all of the App Servers that are configured on your MarkLogic Server.

http://englab.marklogic.com:8000/qconsole/

xquery version "1.0-ml";
xdmp:host-status(xdmp:host("englab.marklogic.com"))

<converters-version>9.0-4</converters-version>

'use strict';
xdmp.hostStatus(xdmp.host("englab.marklogic.com"))

"convertersVersion" : "9.0-4"

Configuring the First and Subsequent Hosts

The following configuration procedures different depending on if you run MarkLogic Server in a cluster configuration or on a single host. The procedures are as follows:

• Configuring a Single Host or the First Host in a Cluster
• Configuring an Additional Host in a Cluster
• Leaving a Cluster and Becoming a Single Host

If you are configuring MarkLogic Server as a standalone host, or if this is the first host in a cluster configuration, follow the installation instructions in Section 2.4.1. Otherwise, follow the installation instructions in Section 2.4.2.

If you are upgrading a cluster to a new release, see Upgrading a Cluster to a New Maintenance Release of MarkLogic Server in the Scalability, Availability, and Failover Guide. The Security database and the Schemas database must be on the same host, and that host should be the first host you upgrade when upgrading a cluster.

Entering a License Key

MarkLogic will run without a license key, but after installing MarkLogic you should enter a valid license key for the usage and features for which you are licensed. At any time, you can change the license key for a host from the Host Status page.

You might need to change the license key if your license key expires, if you need to use some features that are not covered in your existing license key, if you upgrade your hardware with more CPUs and/or more cores, if you need a license that covers a larger database, if you require different languages, or for various other reasons. Changing the license key sometimes results in an automatic restart of MarkLogic (for example, if your new license enables a new language).

To change the license key for a host, perform the following steps using the Admin Interface:

1. Click the Hosts icon on the left tree menu.
2. Click the name of the host for which you want to change the license key, either on the tree menu or the summary page. The Host Configuration page appears.
3. Click the Status tab. The Host Status page appears.
4. Click the License Key button. The License Key Entry page appears.
5. Enter your new license key information. For information about licensing of MarkLogic Server, contact your MarkLogic sales representative.
6. After entering valid information in the Licensee and License Key fields, click OK. If it needs to, MarkLogic will automatically restart, and the new license key will take effect.

Checking for the Correct Software Version

After logging in with your admin username and password, the Admin Interface appears. In the left corner of the Admin Interface, the version number and product edition are displayed.

To view more details about the release of MarkLogic Server that is installed and licensed, complete the following steps:

1. Click the Hosts icon on the left tree menu.
2. Select the name of the host you just installed, either from the left menu tree or from the Host Summary page.
3. Click the Status tab. The Host Status page appears.
4. Check that <version> is correct.

   

To begin using MarkLogic Server, see the following document:

• Getting Started With MarkLogic Server

Otherwise, you are finished with the Admin Interface for now. You have successfully installed MarkLogic on your system.

Configuring MarkLogic Server to Run as a Non-Daemon User

On UNIX-based systems (Linux), MarkLogic runs as the UNIX user named daemon. This section describes how to change a configuration to run as a different named UNIX user. This procedure must be run by the root user. Additionally, the root user is still required for installing and uninstalling MarkLogic and for starting and stopping MarkLogic from the startup scripts.

To modify an installation to run as a user other than daemon, perform the following steps:

1. In a command window on the machine in which you installed MarkLogic, log in as the root user.
2. Make sure MarkLogic is stopped. If it is still running, stop it as follows:

   Platform	Perform the following to stop MarkLogic:
   Red Hat Linux	As the root user, enter the following command: /sbin/service MarkLogic stop

3. Edit the configuration file for your platform using a text editor such as vi.

   Platform	Configuration File to Edit
   Red Hat Linux	/etc/marklogic.conf

   You must create the /etc/marklogic.conf file if it does not exist. This file is only read by the MarkLogic startup; it is never written to; therefore, it will survive an uninstallation of MarkLogic.

4. In the file, edit the MARKLOGIC_USER environment variable to point to the user in which you want MarkLogic Server to run. For example, if you want it to run as a user named raymond, change the following line:

   export MARKLOGIC_USER=daemon

   to the following:

   export MARKLOGIC_USER=raymond

5. Save the changes to the /etc/marklogic.conf file.
6. If you have not yet started MarkLogic after performing a clean installation (that is, after installing into a directory where MarkLogic has never been installed), then you are done and you can skip the rest of the steps in this procedure. If you have an existing installation (for example, if you are upgrading to a maintenance release), then continue with the following steps.
7. For all of the MarkLogic files owned by daemon, you need to change the owner to the new user. This includes all forest data and all of the configuration files. By default, the forest data is in the following directories:

   Platform	Default Data Directory (for configuration and log files, and default forest directory)
   Red Hat Linux	/var/opt/MarkLogic

   For example, on a Linux system, perform a command similar to the following, which changes the owner to the user specified earlier in the /etc/sysconfig/MarkLogic file:

   chown -R raymond /var/opt/MarkLogic

8. Make sure to change the owner for all forests in the system, otherwise forests will fail to mount upon startup. Note that the above command only changes the owner for forests installed in the default directory. You need to run a similar command on the data directory for each forest in which a data directory is specified.
9. When you have completed all the file and directory ownership changes, start MarkLogic as described in Starting MarkLogic Server.

Once you have performed this procedure, all new files created by MarkLogic are created with the new user ownership; there will be no need to change any ownership again.

On Linux systems, use the /etc/marklogic.conf script to set environment variables. Any configuration changes you make to the MarkLogic-supplied startup script (for example, /etc/sysconfig/MarkLogic) will not survive an upgrade and need to be merged in during any upgrade of MarkLogic (because the installation installs a new version of the startup scripts). Under Linux, the unistallation process saves an old version of the scripts (for example, /etc/sysconfig/MarkLogic.rpmsave), so you can use that version to merge in your changes. If you perform a clean installation (not an upgrade installation), however, you will need to run this entire procedure again. If you use /etc/marklogic.conf for your environment variable changes, they will survive an upgrade and you will not need to merge your changes.

The following are default values of environment variables you can override in /etc/marklogic.conf on Linux-based systems (you will have to create the file if it does not exist):

export MARKLOGIC_INSTALL_DIR=/opt/MarkLogic 
export MARKLOGIC_DATA_DIR=/var/opt/MarkLogic
export MARKLOGIC_FSTYPE=ext4
export MARKLOGIC_USER=daemon
export MARKLOGIC_PID_FILE=/var/run/MarkLogic.pid
export MARKLOGIC_UMASK=022
export MARKLOGIC_DISABLE_JVM=0
export MARKLOGIC_EC2_HOST
export TZ=:/etc/localtime

Removing MarkLogic

To remove MarkLogic from your system, complete the following steps for the corresponding platform:

Using this procedure to remove MarkLogic from your system will not remove user data (configuration information, XQuery files used by HTTP or XDBC servers, or forest content). This data is left in place to simplify the software upgrade process. If you wish to remove the user data, you must do so manually using standard operating system commands.

In case you previously used converters/filters and want to remove this functionality:

• To remove MarkLogic Converters from a node that has MarkLogic 9.0-4 or later release installed, you can use package management tool, such as Control Panel on Windows or rpm on Linux, to uninstall MarkLogic Converters.
• To remove converters/filters from a node that has MarkLogic 9.0-3 or earlier release installed, you need to uninstall that release of MarkLogic, and then install MarkLogic Server from release 9.0-4 or later but do not install MarkLogic Converters.