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

REST Application Developer's Guide — Chapter 8

Migrating REST Applications

This chapter describes how to migrate an application hosted on a MarkLogic REST 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 Application Builder, the MarkLogic REST API, or the MarkLogic Java API.

The following topics are covered:

Before You Begin

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

  • MarkLogic Server 6.0-2 or later on both the source and destination hosts.
  • MarkLogic Content Pump (mlcp), XQSync, or an equivalent tool capable of copying content and metadata from one MarkLogic Server database to another.

To download and install mlcp, see Using MarkLogic Content Pump in the Loading Content Into MarkLogic Server Guide.

  • curl or an equivalent tool for sending HTTP requests; see Introduction to the curl Tool.
  • Administrative user privileges on the source and destination MarkLogic Server instances.

In addition, your application must be running on a MarkLogic REST API instance created with MarkLogic Server 6.0-2 or later. If your source application was not created or deployed for the first time on the source host using MarkLogic Server 6.0-2, see Upgrading Your Application to a New REST API Instance.

Upgrading Your Application to a New REST API Instance

You can skip this section if you never installed MarkLogic Server 6.0-1 on your source host.

Between versions 6.0-1 and 6.0-2, changes were made to the MarkLogic REST API to facilitate application migration. If you are migrating an application running on a REST API instance created with MarkLogic Server 6.0-1, you must first upgrade the instance to MarkLogic Server6.0-2 or later.

Your application is likely to be running on a MarkLogic Server 6.0-1 REST API instance if any of the following conditions are met, even if you subsequently upgraded from MarkLogic Server 6.0-1 to 6.0-2 or later:

  • You created your application on the source host using MarkLogic Server 6.0-1.
  • You deployed an existing application to the source host when it was running MarkLogic Server 6.0-1.

If you meet one of these criteria, you must re-host your application on a new REST API instance. Choose from one of the following procedures:

Upgrading an Application Builder Application

This procedure moves your source application to a new REST API instance. You only need to perform this procedure if your application was created with Application Builder and one of the following conditions is true.

  • You created your application on the source host using Application Builder and MarkLogic Server 6.0-1.
  • You initially deployed your application on the source host using Application Builder and MarkLogic Server 6.0-1. This applies even if you subsequently upgraded the source host to MarkLogic Server 6.0-2 or later because the upgrade does not recreate the REST API instance.

If your application was not created with Application Builder, see Upgrading Other Applications.

If one of the above conditions is met, you must redeploy your application on a REST API instance created with MarkLogic Server 6.0-2 or later before migrating it to a new host. Doing so picks up changes that support seamless application migration across hosts.

This procedure will change the REST API instance name and the port number on which your application runs.

To create a new REST API instance for your application:

  1. If the source host is not already running MarkLogic Server 6.0-2 or later, upgrade to MarkLogic Server 6.0-2 or later.
  2. In your browser, navigate to the Application Services page on your source host. For example, navigate to:
    http://localhost:8000/appservices
  3. Click the name of your application in the list of Application Builder Applications. The Search page appears.
  4. Click on Deploy at the top of the page. The Deploy page appears.
  5. Select New REST API Instance on the Deploy page.
  6. Accept the default name and port number, or enter a name and port number different from the App Server name and port number currently used by your application.
  7. Click Deploy. Your application is deployed on a new REST API instance.
  8. If your application includes extensions or customizations, re-install them to the modules database of the new App Server. For details, see Extending Applications Built With Application Builder in the Application Builder Developer's Guide.
  9. Test your application on the new REST API instance.
  10. Optionally, delete the old REST API instance and associated modules database using curl or an equivalent tool. For details, see Removing an Instance. Deleting the REST API instance will cause a server restart. For example, if your source host is localhost and your REST API instance name is 'Oscars':
    # Windows users, see Modifying the Example Commands for Windows$ curl --anyauth --user user:password -X DELETE -i \
        http://localhost:8002/v1/rest-apis/Oscars?include=modules

Upgrading Other Applications

This procedure moves your application to a new REST API instance. Use this procedure only if both of the following conditions are met.

  • Your application was not created using Application Builder. If your application was created with Application Builder, see Upgrading an Application Builder Application.
  • Your application is running on the source host on a REST API instance created using MarkLogic Server 6.0-1.

If you meet both these conditions, perform the following steps on your source host before migrating your application to a new host:

  1. If the source host is not already running MarkLogic Server 6.0-2 or later, upgrade to MarkLogic Server 6.0-2 or later.
  2. Delete the current REST API instance and associated modules database. For details, see Removing an Instance. Deleting the REST API instance will cause a server restart. For example, assuming your source host is localhost and your REST API instance name is 'Oscars':
    # Windows users, see Modifying the Example Commands for Windows$ curl --anyauth --user user:password -X DELETE -i \
        http://localhost:8002/v1/rest-apis/Oscars?include=modules
  3. Recreate the REST API instance using Information Studio or the MarkLogic REST API. For details, see Creating an Instance. This example uses the REST API with a previously saved configuration file:
    $ cat config.xml
    <rest-api xmlns="http://marklogic.com/rest-api">
      <name>Oscars</name>
      <database>Oscars</database>
      <port>8003</port>
    </rest-api>
    $ curl -X POST --anyauth --user user:password -d @"./config.xml" \
        -H "Content-type: application/xml" \
        http://localhost:8002/v1/rest-apis
  4. If you modified the default REST API configuration properties, set them again. For details, see Configuring Instance Properties.
  5. If your application includes custom query options, content transformations, or resource service extensions, redeploy them to the new instance. For details, see Creating or Modifying Query Options, Installing Transformations, Installing a Resource Service Extension.

Migrating the Content Database

Use this procedure to migrate your application content database configuration and contents to the destination host. You must do this before migrating the REST API instance as described in Migrating the REST API Instance.

If the content database already exists on the destination host, its configuration may be changed by this procedure. You will have a chance to review the changes when importing the source configuration.

If the content database does not already exist on the destination, it will be created for you.

  1. Export the content database configuration on the source MarkLogic Server instance using Configuration Manager. For details, see Exporting a Configuration in the Administrator's Guide. An XML file that contains the configuration is created.
  2. Import the content database configuration file created in the previous step to the destination MarkLogic Server instance using Configuration Manager. For details, see Importing a Configuration in the Administrator's Guide. An empty content database is created on the destination instance.
  3. Copy the content from the source database to the destination database using MarkLogic Content Pump (mlcp), XQSync, or a similar tool. To use mlcp to copy your content:
    1. Create an XDBC App Server attached to the content database on the source host. For details, see Creating a New XDBC Server in the Administrator's Guide.
    2. Create an XDBC App Server attached to the content database on the destination host.
    3. 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 Loading Content Into MarkLogic Server Guide. For example:
      $ mlcp.sh copy -mode local \
          -input_host src-host -input_port src-xdbc-port \
          -input_username user -input_password password \
          -output_host dest-host -output_port dest-xdbc-port \
          -output_username user -output_password password
    4. If you cannot reach the 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 to an Archive and Importing Content Into MarkLogic Server in the Loading Content Into MarkLogic Server Guide. For example:
      # Export the source database content to an archive
      $ mlcp.sh export -mode local -output_type archive \
          -host src-host -port src-xdbc-port \
          -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 -port dest-xdbc-port \
          -username user -password password 
          -input_file_path dir-containing-archive

You can now remove the XDBC App Servers created during this procedure, or save them to re-use for migrating the REST API instance.

Migrating the REST API Instance

Use this procedure to migrate your application configuration and logic to a new REST API instance on the destination host. This step creates a new REST API instance on the destination host, and then overwrites the configuration and code it contains with the equivalent information from the source instance.

If the destination is a multi-host MarkLogic Server cluster, you only need to perform this procedure on one E-node.

The content database must exist on the destination host before performing this procedure. For details, see Migrating the Content Database.

  1. On the destination host, create a new REST API instance with the same group, name and port number as the source App Server. For details, see Creating an Instance. Use the database created in Migrating the Content Database as the content database.
  2. On the destination host, create any MarkLogic Server users and roles required by your application. Use the same user and role name as on the source host.
  3. Use MarkLogic Content Pump, XQSync, or a similar tool to copy the REST API instance modules database from the source to the destination. To use mlcp to copy your content:
    1. On the source host, create an XDBC App Server attached to the REST API instance modules database. For example, if your REST API instance is named 'Oscars', the default modules database name will be 'Oscars-modules'.
    2. On the destination host, create an XDBC App Server attached to the modules database of the REST API instance created in Step 1.
    3. If the source and destination hosts are both reachable from the host where you are running mlcp, use the mlcp copy command, as described in Copying Content Between Databases in the Loading Content Into MarkLogic Server Guide. For example, you can use a command of this form:
      $ mlcp.sh copy -mode local \
          -input_host src-host -input_port src-xdbc-port \
          -input_username user -input_password password \
          -output_host dest-host -output_port dest-xdbc-port \
          -output_username user -output_password password
    4. If you cannot reach the both the source and destination host from the same host, use the mlcp export and import commands, as described in Exporting to an Archive and Importing Content Into MarkLogic Server in the Loading Content Into MarkLogic Server Guide. For example:
      # Export the source modules database content to an archive
      $ mlcp.sh export -mode local -output_type archive \
          -host src-host -port src-xdbc-port \
          -username user -password password \
          -output_file_path an-existing-directory
      # one or more ZIP files are created in the output directory
      # Import the archive to the destination modules database
      $ mlcp.sh import -mode local -input_file_type archive \
          -host dest-host -port dest-xdbc-port \
          -username user -password password 
          -input_file_path dir-containing-archive

Your application should now be usable with the destination MarkLogic Server instance.

« Previous chapter
Next chapter »