Creating a WAR File for Epubcheck

Note: I've made some changes to this post as a result of the build mechanism for epubcheck-3.0-RC-1 moving to using Apache Maven. More details can be found in our current repository on github.

If, like me, you do a lot of EPUB creation, you therefore find presumably yourself doing a lot of EPUB validation.

Although we've seen more validation tools emerge in recent times, the standard is still epubcheck, a Java archive that can be used to check the validity of EPUB files at the command line:

$java -jar epubcheck [name of epub file]

Last year (back when EPUB3 was still twinkling in its makers eyes), releases of the epubcheck Java .jar file were accompanied by a .war file, which was very useful as it could be hosted by a Java-based webserver (e.g. Apache Tomcat), and used to provide a web-based interface for EPUB validation using epubcheck. This is how the the IDPF offer their online EPUB validation service.

However, recent builds of epubcheck have not been accompanied by this .war file meaning that, for your own purposes, you were looking at having to use the command line version, as described above. You could still of course use the IDPF's online validation service, but this is only for non-commercial use and for files less than 10MB.

So, after running into a confused situation where a client mistakenly thought their EPUB3 was invalid because it was being checked against an older version of the epubcheck .war file used by a web service, I thought it was high time I worked out how to create a .war from a recent release.

As epubcheck is written in Java and not being a Java programmer myself (and there's good reason for this, summed up nicely in this post about Execution in the Kingdom of Nouns), I was a little tremulous about tackling this, but it actually turned out to be relatively easy.

The steps are below, and the presumption is that you're running either  a Debian / Ubuntu distribution, or Cygwin on Windows.

Get the latest epubcheck

Download the binary latest version of epubcheck, and extract the zip file. Inside you should find the compiled .jar file (e.g. epubcheck-3.0-RC-1.jar) and the lib folder.

Extract epubcheck

Make a new folder called epubcheck and inside create a subfolder called com.adobe.epubcheck.

Inside the com.adobe.epubcheck folder, create a dist folder and copy into this the compiled .jar file extracted from the zip file in the previous step.

Also, copy the lib folder extracted from the zip file in the previous step such that it's a direct subfolder of com.adobe.epubcheck.

Get the epubcheck .war compilation code

Checkout a subtree of the epubcheck code trunk, which contains the files needed for building the .war. It appears that all the epubcheck development has taken place in branches, and has not been merged back into the trunk, and therefore some of the code in the trunk is quite old, but that's fine for the bit of the trunk that we need to build the .war. Inside the epubcheck folder:

svn checkout ./epubcheck/com.adobe.epubcheck.web</pre>

Tweak the build file

Make some changes to the build file, com.adobe.epubcheck.web\build-war.xml, specifically,

  • Include the correct version number, as found in the name of .jar file

  • Remove the epubcheck dependency from the compile step, as we'll be using the downloaded .jar file:

      <!-- <target name="compile" description="Compiles all src classes" depends="removeClasses, epubcheck"> -->
  • Remove the buildEpubCheckWAR dependency from the compile step:

      <!-- <target name="buildEpubCheckWAR" description="creates epubcheck war file" depends="createDistributionDir, epubcheck, compile" > -->

Customise the HTML

If you want to customise the HTML and CSS used for the web service, then make the amendments to the code in com.adobe.epubcheck.web\http_root

Build the .war

ant -f com.adobe.epubcheck.web/build-war.xml

Install the .war

/etc/init.d/tomcat stop
cd /usr/local/tomcat/webapps
cp /tmp/epubcheck/com.adobe.epubcheck.web/dist/epubcheck-3.0-RC-1.war epubcheck.war
/etc/init.d/tomcat start

Restart Tomcat

Once Tomcat's restarted, you should be able to see the epubcheck service at http://localhost:8080/epubcheck.

On my system I use Apache to proxy requests from port 80 to 8080, so I can make it available as I do at