Loading TOC...
REST Application Developer's Guide (PDF)

MarkLogic 10 Product Documentation
REST Application Developer's Guide — Chapter 10

« Previous chapter
Next chapter »

Migrating REST Applications

This chapter describes how to migrate an application hosted on a REST Client API instance from one MarkLogic Server installation to another, such as migrating an application from your development environment to a test or production environment.

These instructions only apply to applications that depend on a REST API instance, such as those created with the REST Client API or the MarkLogic Java API.

The following topics are covered:

Before You Begin

Migrating a REST API application requires migrating the REST API instance (an App Server and modules database) and your content database. The REST API instance and the configuration of your content database are migrated using Configuration Manager. You can migrate the contents of your content database using any tool, but this guide assumes MarkLogic Content Pump (mlcp).

The migration procedure outlined by this chapter assumes you have the following:

Migrating the REST API Instance and Database Configuration

Use Configuration Manager to migrate your REST API instance and the configuration of your content database from to the destination MarkLogic Server cluster. If you are not familiar with Configuration Manager, see Using the Configuration Manager in Administrator's Guide.

Export the Configuration from the Source Cluster

This procedure saves the configuration of your content database and REST API instance App Server, and the configuration and contents of the modules database to a ZIP file using Configuration Manager. For detailed instructions on using Configuration Manager, see Exporting a Configuration in Administrator's Guide.

You are not required to include the content database in this step, but if you do not, you must ensure it exists on the destination cluster before importing the REST API instance configuration.

  1. Open the Configuration Manager on the source cluster in your browser. Authenticate as a user with the manage-admin role or equivalent privileges. For example, navigate to:
    http://source-host:8002/nav
  2. Click on the Export tab. The Package Export interface is displayed.
  3. If you want to migrate your content database configuration, place a check in the Settings column for your content database.
  4. Click on Servers in the left column. Configuration Manager displays the App Servers available for export.
  5. Place a check in the Settings and Modules columns for your REST API instance App Server.
  6. Click the Export button in the upper right corner and select a location and name for the exported configuration ZIP file.

Import the Configuration to the Destination Cluster

This procedure uses Configuration Manager and the ZIP file created in Export the Configuration from the Source Cluster to re-create your content database and REST API instance on the destination MarkLogic Server cluster. For detailed instructions on using Configuration Manager, see Importing a Configuration in Administrator's Guide.

If you did not include your content database configuration in the ZIP file, you must ensure that the content database exists on the destination cluster before performing this procedure.

  1. Open the Configuration Manager on the destination cluster in your browser. Authenticate as a user with admin privileges. For example, navigate to:
    http://dest-host:8002/nav
  2. Click on the Import tab. The Package Import interface is displayed.
  3. Click the Browse button and browse to the ZIP containing your configuration.
  4. Click Compare to import the package. The package contents are displayed. No configuration changes have been made at this time.
  5. Click Apply. Configuration Manager re-creates the packaged configurations and the contents of the modules database.
  6. On the destination cluster, create any MarkLogic Server users and roles required by your application. Use the same user and role name as on the source host.

Your REST API instance is fully functional at this point, including any resource extensions, persistent query options, or transformations stored in the modules database. If you imported your content database, then the database and its forests exist, but the database is still empty.

You can use the Admin Interface or Configuration Manager to confirm the existence of your REST API instance and content database. If you application includes resource extensions, transformations, or persistent query options, you can query them. For example, you can get a list of persistent query options using GET /v1/config/query.

Migrating the Contents of the Database

Use the procedure in this section to migrate the contents of your application content database to the destination cluster. The database must already exist on the destination cluster using mlcp. You can also use XQSync or a similar tool to copy the contents.

The following procedure copies the entire contents of the source content database into the destination content database, using mlcp and the XDBC App Server pre-configured on port 8000 when you install MarkLogic 8 or later. If you are using an older version of MarkLogic, you may need to create an XDBC App Server for use with mlcp and explicitly specify the input and/or output port on the mlcp command line.

  1. If the source and destination hosts are both reachable from the host where you perform the copy, use the mlcp copy command, as described in Copying Content Between Databases in the mlcp User Guide. For example:
    $ mlcp.sh copy -mode local \
   -input_host src-host -input_username user -input_password password \
   -output_host dest-host -output_username user \
   -output_password password
  2. If you cannot reach both the source and destination host from the host where you perform the copy, use the mlcp export and import commands, as described in Exporting Content from MarkLogic Server and Importing Content Into MarkLogic Server in the mlcp User Guide. For example:
    # Export the source database content to an archive
$ mlcp.sh export -mode local -output_type archive \
    -host src-host -username user -password password \
    -output_file_path an-existing-directory
# One or more ZIP files are created in the output directory.
# Copy the archive files to a host that can reach the destination host
# Import the archive to the destination database
$ mlcp.sh import -mode local -input_file_type archive \
    -host dest-host -username user -password password 
    -input_file_path dir-containing-archive

« Previous chapter
Next chapter »