Get started

This page guides you through the first steps to work on a project. And beyond. The only requirement is to have MarkLogic installed and running already.

TL;DR

Let us start with a summary of this entire introduction. In case you are in a big rush, that should give you enough to get started.

$ npm install mlproj -g                    # install mlproj
$ mlproj help

$ mkdir my-foobar                          # create a new project
$ cd my-foobar
$ mlproj new

$ mlproj show                              # create the env on MarkLogic
$ mlproj setup

$ mlproj deploy                            # deploy code and load data
$ mlproj load doc some/doc.xml

One more tip though. Using the global option -d enters the "dry run mode". In this mode, no action is actually done, it is only simulated and displayed, so you can inspect first what would happen when you run the command for real. For instance for the command setup:

$ mlproj -d setup

And now for some more explanations...

Projects

First of all, what do we mean by "project"?

With mlproj, a project is any consistent set of source code, typically deployed in an app server modules database. This definition is rather vague (it is not a definition, really), and this is on purpose. This gives you an idea of what it is meant to do, but it is up to you if you want to use it in another way.

This is basically the same definition of "project" as in any IDE.

In code project management, there is rarely one-size-fits-all. So mlproj tries not to constrain you too much, and you can use it with your project, complying to its existing rules and conventions, however crazy these rules are (with a very few exceptions.)

Once and for all

Before starting wih mlproj, you need to install it on your computer. This has to be done only once:

$ npm install mlproj -g

You can validate that the install was successful by displaying the main help message:

$ mlproj help

The npm install command has to be invoked only once. But you can also use it again later to upgrade to the latest version. Since mlproj evolves quite rapidly at the moment, it is recommended you use it for time to time.

New project

Create a new project is as easy as invoking the command new, and answering a few questions interactively. It has to be invoked from an empty directory:

$ mkdir my-foobar
$ cd my-foobar
$ mlproj new
--- Questions ---
Project code    : my-foobar
Title           : My own foobar project
Name URI (http://mlproj.org/example/my-foobar): http://example.org/my-foobar
Version  (0.1.0):
Port     (8080) :

--- Summary ---
 Project created:      my-foobar
 Check/edit files in:  /home/fgeorges/tmp/my-foobar/xproject
$ 

The values within parentheses are the default values to use, if you hit the enter key without typing anything.

As the summary message suggests, files have been created in a new sub-directory xproject/, in the current directory. This new directory contains the project descriptor, as well as the environment files. More on that later, but for now, just have a look at them and, if MarkLogic is installed on localhost:

  • adapt user and password in xproject/mlenvs/dev.json

If not:

  • adapt user, password, and host in xproject/mlenvs/prod.json
  • change "dev.json" into "prod.json" in xproject/mlenvs/default.json

Check settings

Congratulations, you have just created your first project! Now invoke the command show, to see how it has been configured and if nothing has to be changed:

$ mlproj show

Project: my-foobar
   title:               My own foobar project
   name:                http://example.org/my-foobar
   version:             0.1.0

Environment: default
   host:                localhost
   user:                admin
   password:            *****
   sources dir:         /home/fgeorges/tmp/my-foobar/src/
   modules DB:          (filesystem)
   parameters:
      port:             8080
   import graph:
      -> dev.json
         -> base.json

Database: my-foobar-content
   id:                  content
   forests:
      my-foobar-content-001

Server: my-foobar
   group:               Default
   id:                  app
   content DB:          my-foobar-content
   port:                8080
   root:                /home/fgeorges/tmp/my-foobar/src/

$ 

What you see here is pretty self-explanatory:

  • information about the project itself (essentially what you fed the command new with)
  • the environment details (connection, parameters, import graph)
  • each database and server in the environment, with their details

If anything must be changed, look at the files in xproject/mlenvs/, and see if you can adapt the corresponding value. All details are in the environment format documentation.

On MarkLogic!

So what is the point of all this, if it is not to create the corresponding components (databases and application servers) on MarkLogic? To do so, nothing more simple:

$ mlproj setup
--- Prepare ---
 checking the database:      my-foobar-content
 Retrieve database props:    my-foobar-content
  need to create database:    my-foobar-content
    checking forests
     need to create forest:   my-foobar-content-001
 checking the http server:   my-foobar
 Retrieve server props:      my-foobar
  need to create server:      my-foobar

--- Progress ---
 Create database:            my-foobar-modules
 Create forest:              my-foobar-modules-001
 Create database:            my-foobar-content
 Create forest:              my-foobar-content-001
 Create server:              my-foobar

--- Summary ---
Done:
 Create database:            my-foobar-modules
 Create forest:              my-foobar-modules-001
 Create database:            my-foobar-content
 Create forest:              my-foobar-content-001
 Create server:              my-foobar
$ 

As you can see, mlproj first gather all information about what needs to be created, changed, or updated, and accumulate the list of actions to be done before actually executing them. This maximizes the detection of errors before starting to make any change.

In case of any error, processing stops. The summary gives the list of completed actions, the error details, then the list of actions that were still to be executed at the time.

Deploy code

Now, let us simulate hours and days and weeks of work, by creating the following modules in the src/ directory. Feel free to use JavaScript instead if this is your language of choice. The goal is just to get some files in src/.

Note - Deploying code to the modules database is only required (and does only make sense) when the app server is attached to a modules database, as opposed to accessing the modules directly on the locahost file system. With the default environment files, this means you need to deploy only if you use prod.json, not with dev.json (which is the default). Trying to deploy with the latter will result in an error.

This is src/lib/foo.xqy:

module namespace foo = "http://example.com/foobar/lib/foo";

declare function foo:hello($who)
{
   'Hello, ' || $who || '!'
};

And this is src/endpoints/bar.xqy:

import module namespace foo = "http://example.com/foobar/lib/foo"
   at "../lib/foo.xqy";

foo:hello('world')

Now we can deploy the code to the modules database (remember you can use the -e option to use another environment than the default one, like this: mlproj -e prod deploy).

$ mlproj load

--- Prepare ---
 checking the directory:     src
 checking the directory:     src/endpoints
 checking the directory:     src/lib

--- Progress ---
 Insert documents:           2 documents

--- Summary ---
Done:
 Insert documents:           2 documents, for 0.000 Mo
$ 

Load data

The last step you might need in order to play with a project is the ability to load some document. For that, put the files in the directory data/ and use the command load. For instance, create the file data/hello.xml with the following content:

<greetings>
   <who>World</who>
</greetings>

and the file data/foo/bar.json:

{ "answer": 42 }

Then load it in the content database:

$ mlproj load

--- Prepare ---
 checking the directory:     data
 checking the directory:     data/foo

--- Progress ---
 Insert documents:           2 documents

--- Summary ---
Done:
 Insert documents:           2 documents, for 0.000 Mo
$ 

By default, the URI of the resulting document in the database is computed as the path of the file under data/. In our example, documents are saved under:

  • /hello.xml
  • /foo/bar.json

See the documentation if you need to customize the document URIs.

What now?

This quick overview should give you enough to get started: install mlproj, create a new project, create its databases and app servers on MarkLogic, deploy the code, and load some data.

The next steps now, if you want to learn more, is to have a look at:

  • the list of commands available
  • the description of the environment files, to describe the components to create on MarkLogic (databases and app servers) and their properties (indexes, URL rewriter, etc.)

Have fun!