Printer-friendly version

UPDATED: Brief Mercurial usage section at end. I'll probably break that off as a separate, free tutorial in a day or two if you want to check back.

MORE UPDATED: What was supposed to be a short, concise tutorial seems to be getting out of hand. I already predict a rewrite that's a bit more organized. *Sigh*. In my copious free time.

The wiki/blog page that will not die

It started innocently enough, over beers, with a couple local colleagues discussing the need to start collecting, managing and categorizing what will potentially be tens of thousands of valuable digital images. One suggestion led to another and, long story short, the fully open source Nuxeo DAM (Digital Asset Management) software, and it's apparently my job to explain how to do it and perhaps make it happen so, rather than constantly answer their e-mails, I'll explain it once and for all and they'll stop pestering me.

If anyone else finds this page (and finds it useful), you're welcome. If we ever meet, I drink single malt.

(There's an earlier version of this writeup here, but the page you're reading is the latest and most complete version, so you can ignore that Wiki page.)

Also, some of what's here might be slightly speculative, and I'm willing to be corrected. I'll leave the comments section open for that.

The Linux distro and the packages

These days, I spend most of my time immersed in a fully-updated Ubuntu 10.04 system so, for Nuxeo DAM, you'll want at least the following:

$ sudo apt-get install gimp imagemagick ffmpeg ufraw poppler-utils

plus the standard OpenOffice packages if you use them as part of your Nuxeo DAM sessions.

In addition, if you plan on building DAM from source (and I'll explain why you might want to do that later), you'll want:

$ sudo apt-get install maven2 mercurial

Finally, depending on which Java servlet engine you plan on using (and here's a bit of that speculation), you'll want one of:

$ sudo apt-get install jbossas4 tomcat6 jetty

You'll get an idea of which one to install later. Onward.

Which Java?

While Nuxeo DAM officially requires Sun's Java, I've had no issues using the standard OpenJDK 6 packages that are available with Ubuntu, but it may just be that I haven't pushed the software hard enough to find any incompatibilities. Thus:

$ sudo apt-get install openjdk-6-jdk

and verify that's installed properly with:

$ java -version
java version "1.6.0_18"
OpenJDK Runtime Environment (IcedTea6 1.8) (6b18-1.8-0ubuntu1)
OpenJDK 64-Bit Server VM (build 14.0-b16, mixed mode)
$

Running Nuxeo DAM 1.0

If you're happy with the current release of Nuxeo DAM, you can just grab it from here, but note that the only current choice seems to be the Tomcat-based download so it appears you'll need to install Tomcat, and you can just follow along in the Quickstart Guide here. All of that's suitably straightforward so I'm not going to flog it any further.

Building Nuxeo DAM from source

Rather than simply use the pre-built Tomcat-based 1.0 version, you can live life on the edge and build it from source, for one of a number of reasons:

• because you want to see the new features on the development branch,
• because there's been some very nice refactoring of code since version 1.0,
• because you want to try to build a non-Tomcat-based version (Jetty or JBoss), or
• because you're bored and it sounds like fun.

Pick whatever reason works for you.

Getting the packages and the source

If you want to build from source, you'll need the packages:

$ sudo apt-get install mercurial maven2

at which point you can grab the Mercurial-based source repository with:

$ hg clone http://hg.nuxeo.org/nuxeo-dam

By default, once your download finishes, you can change into that directory and verify that you're on the development branch:

$ cd nuxeo-dam
$ hg branch
develop        <-- that's what you want to see
$

and now you're ready to build. And here's where I'm going to get a bit speculative.

The first phase of the build

As I read it, you build the final distribution zip file in two phases. First, there's the servlet engine-independent part, where you run the following command at the top-level directory of the source:

$ mvn clean install

after which you eventually want to see:

... snip ...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Nuxeo DAM Parent ...................................... SUCCESS [7.854s]
[INFO] Nuxeo DAM Core ........................................ SUCCESS [2:57.656s]
[INFO] Nuxeo DAM WebApp Core ................................. SUCCESS [1:48.663s]
[INFO] Nuxeo DAM WebApp Contributions ........................ SUCCESS [1.185s]
[INFO] Nuxeo DAM WebApp ...................................... SUCCESS [2.906s]
[INFO] Nuxeo DAM WebApp Override ............................. SUCCESS [0.972s]
[INFO] Nuxeo DAM Language pack ............................... SUCCESS [1.194s]
[INFO] Nuxeo DAM Importer .................................... SUCCESS [31.544s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5 minutes 47 seconds
[INFO] Finished at: Thu Jun 24 16:56:58 EDT 2010
[INFO] Final Memory: 174M/469M
[INFO] ------------------------------------------------------------------------

But that's only the first part.

The second half of the build

That first part up there is the servlet engine-independent part. To build the final distribution zip file, you need to:

$ cd nuxeo-dam-distribution
$ mvn clean install -Ptomcat  [or -Pjboss or ...]

which should be self-explanatory, but here's where you might run into an issue that's not your fault.

Part of the build process requires downloading numerous zip files from one of Nuxeo's web pages and when some of those zip files are being updated to the latest versions, it's apparently normal for required zip files to be unavailable for an hour or longer, so don't be surprised if an attempted download simply sits there for a while, then aborts with a "502, not found" error. It just means you should try again later -- there's nothing else you can do about it.

Eventually, all of the files will be available, but it's still moderately aggravating to have to wait for an hour or two while new files are uploaded to a web server.

Building for JBoss

It should be obvious how you'd try to build a JBoss version of the software:

$ mvn clean install -Pjboss

Sadly, that's also currently failing trying to fetch unavailable files. Oh, well.

Running the result

Once you have a successful build, the corresponding zip file can be found under the directory nuxeo-dam-distribution/target. In my case, I get a file named nuxeo-dam-distribution-1.1-SNAPSHOT-tomcat.zip which I can unzip anywhere I want, then run with:

$ sh bin/nuxeoctl start

If all goes well, I should then be able to browse to the URL http://localhost:8080/nuxeo to find my development version of Nuxeo DAM waiting for me to login. Success. Victory is mine!

Keeping up to date with developments

To stay on top of commits to the development branch, just run:

$ hg pull -u

every so often at the top level of the Nuxeo DAM source directory to see if it's worth rebuilding. (Perhaps a short Mercurial tutorial would not be amiss here.)

If I've forgotten anything, I'm sure someone will point it out. And now my colleagues can stop hassling me. Until they get a sudden urge for document management as well. I suspect that will require another evening involving more beer.

Acknowledgements

Many thanks to Nuxeo's Thomas Roger, for answering a number of technical questions related to the above. I probably owe him a beer by now.

Unhappy afterthoughts

Nuxeo's inability to keep their Maven metadata XML files synced with their corresponding zip files in their download repository makes building from source a painful exercise at times. This shouldn't be happening. How hard would it be to simply leave the metadata XML files referring to fully uploaded zip files until the newer ones are in place?

[UPDATE, JUN 25] Jetty? What about Jetty?

Recall that I mentioned yet another alternative for a Java servlet engine -- Jetty. But there is no active profile to build a Jetty-specific release of Nuxeo DAM for Jetty as you can for Tomcat (and here's where I'm going to get speculative).

Theoretically, it shouldn't matter what servlet engine you choose to run. I'll let Ubuntu mailing list member Carlos A. Carnero Delgado explain it:

"If the application is built and packaged according to the
Servlet specs, then it is possible to deploy it anywhere.
Only if it uses a service or facility that one container
provides but the other does not, you'll run into problems.

"For instance, JTA [Java Transaction API] is not guaranteed
to be available in these servlet containers, so people often
use a third party implementation and package it with the
application instead of relying on the existence (or not)
of JTA across every servlet container.

"If you can, try to adhere as strictly as possible to the
servlet specification when developing the application.
Then pay close attention to the version of the spec it was
developed against, choosing the servlet containers that
implement those versions. You won't have many problems,
IMO."

Technically, then, if you build for Tomcat, you should be able to run the resulting build against Jetty and, in fact, if you run:

$ mvn clean install -Pjetty

what you read is:

... snip ...
[WARNING] 
	Profile with id: 'jetty' has not been activated.
...
build:
     [echo] Building Tomcat distribution...
...

which suggests that the Tomcat build should work with Jetty. That makes sense, but I haven't tested it since the explicit Tomcat build is adequate for my experiments. If anyone wants to try it, let me know how that works out and I'll add that here.

Finally ...

The zip files under http://maven.nuxeo.org finally synced up so I dashed off a couple builds:

$ mvn clean install -Ptomcat
$ mvn install -Pjboss

and I appear to have a couple reasonable zip files. Will test them later and report back.

Mercurial and keeping up with development commits

Since some folks want to know how to check on what's been committed to decide if it's worth rebuilding their DAM zip file, some trivial Mercurial usage, demonstrated with (unsurprisingly) the current Nuxeo DAM source repository.

First, always make sure you're on the development branch:

$ hg branch
develop            <-- there you go
$

Next, pull recently-committed changes as often as you want:

$ hg incoming       [are there any changes?]
$ hg pull -u        [pull them]

What's the most recently committed change? You can display it in either the short or long form (the long form displaying the actual patch that was committed):

$ hg tip
changeset:   668:19df5620f844
branch:      develop
tag:         tip
user:        Thomas Roger 
date:        Fri Jun 25 16:43:10 2010 +0200
summary:     Add Publishable facet to File type

$ hg tip -p     [show patch as diff output]
changeset:   668:19df5620f844
branch:      develop
tag:         tip
user:        Thomas Roger 
date:        Fri Jun 25 16:43:10 2010 +0200
summary:     Add Publishable facet to File type

diff -r 85f98f82a8d7 -r 19df5620f844 ...
... commit diff output displayed here ...

And you can display the log of commits, again either the short or long form, with either of:

$ hg log
$ hg log -p    [with patches]

That's probably all you need for now. I'm thinking that maybe I need a general-purpose Mercurial tutorial for beginners. Later.