Installing “ThePub”

The install instructions provided at ThePub are very nice and concise. Here is a more elaborate description of what I had to do to get it running on FreeBSD.

  • Install Apache Tomcat, Postgresql and JRE. I used JRE 6.0, Postgresql 8.4 and Tomcat6
    On Freebsd, for the JRE, you need to manually download a number of files (the make install in /usr/ports/jdk16 will guide you). However, the tzupdate file referenced in /usr/ports/ is almost always older than that available from Sun/Oracle. You will need to edit the Makefile and description file to include the new tzupdate revision number and year, and also to update the MD5 and SHA256 checksums to reflect that of the file you download
  • Once JRE 6 is installed, and postgresql-server and postgresql-client is also installed, install the postgresql-jdbc

At the end of all the installs, my /usr/ports/distfiles/ contained the following (starting from a virgin FreeBSD 8.0 machine:

apache-ant-1.7.1-bin.tar.bz2				gettext-1.05.tar.gz					m4-1.4.14.tar.bz2
apache-ant-manpage-20030908.tgz				gnome2							make-3.81.tar.bz2
apache-tomcat-6.0.24.tar.gz				gnutls-2.8.3.tar.bz2					openmotif
autoconf-2.62.tar.bz2					help2man-1.37.1.tar.gz					pcre-8.00.tar.bz2
automake-1.10.1.tar.bz2					jdk-6u3-fcs-bin-b05-jrl-24_sep_2007.jar			perl
bsd-jdk16-patches-4.tar.bz2				jdk-6u3-fcs-mozilla_headers-b05-unix-24_sep_2007.jar	postgresql
check-0.9.8.tar.gz					jdk-6u3-fcs-src-b05-jrl-24_sep_2007.jar			python
compat7x-amd64-7.2.702000.200906.1.tar.bz2		libgcrypt-1.4.4.tar.bz2
cups-1.4.2-source.tar.bz2				libgpg-error-1.7.tar.bz2				unzip60.tar.gz
desktop-file-utils-0.15.tar.gz				libiconv-1.13.1.tar.gz					wget-1.12.tar.bz2
diablo-caffe-freebsd7-amd64-1.6.0_07-b02.tar.bz2	libpthread-stubs-0.3.tar.bz2				xcb-proto-1.6.tar.bz2
gamin-0.1.10.tar.gz					libtool-2.2.6b.tar.gz					xorg
gettext-0.17.tar.gz					libxcb-1.5.tar.bz2

Configuring Tomcat and Postgres on FreeBSD

  • Useful links: getting tomcat running on freebsd
  • On FreeBSD, you /etc/rc.conf should now contain, among other things,

  • postgresql_enable="YES"

  • To setup / initialize the postgresql installation. See here for useful notes.
  • Tell postgresql to listen on IP port. See useful links
    Configuring network/runtime of postgresql
  • Add the postgresql jdbc jar file to your Tomcat classpath. I ended up just copying the postgresql.jar file to the lib/ directory under my Tomcat install. You might want to see the following link for more elaborate discussion:
    Setting up Tomcat CLASSPATH
  • Debug your base setup with the java program (and very useful overview) from here.
    You should get to the point where /var/log/messages says a connection was received by postgress, but complains that there is no user “fred”. That is a sanity check that Java can now access postgres
  • Create a user for thepub as described in the ThePub install documents. Also setup a password in postgresql, see link.
    This password will need to go in the db/settings file in ThePub

Some changes needed to ThePub sources

  • Uncompress the thepub.war file in a new empty directory, by
    jar xvf thepub.war You can find more on WAR files here.
  • Edit the file template/header.jsp, and change ‘publics’ to ‘thepub’, so that the dwr and cos can actually be executed. If you don’t do this, the Ajax stuff won’t work, so, e.g. the add publication page will not mark the unfilled fields with red text.
  • Edit the db/settings file with the correct username and password you created in postgresql.
  • Re-archive the edited war using
    jar cvf thepub.jar *
  • Copy thepub.war to your tomcat “webapps” directory. It will be automatically unarchived when you access http://your-ip:tomcatport/thepub
  • Create the directory pubfile/ and pubfile/temp/ under the webapps/thepub directory. I made these writable by the www user that tomcat runs as. If you don’t do this, when adding a Publication, you will always go directly to an error page when selecting publication type. See submitaddpublic.jsp.
  • Create the directory “bibtextFile” (note, don’t be smart, its not “bibtexFile”; there’s a ‘t’ in there). If you don’t do this, the preview after addition of new publications will fail. See previewpub.jsp.

End notes

  • I currently occasionally have the interface suddenly stop reaching the database, showing all empty entries everywhere, not even able to list publication types in the “add new publication”. I have tracked this down to being due to postgres dying, apparently due to semaphores on which it depended being deleted out-of-band. error in /var/log/messages:

    Jan 21 10:29:28 somehostname postgres[26088]: [4-1] FATAL: semctl(2752546, 3, SETVAL, 0) failed: Invalid argument

    I initially thought this might be because even though I had enabled postgres through /etc/rc.conf on FreeBSD, I was starting/stopping it manually. It still occurs even though I start all services via /etc/rc. See for a nice overview of the right way to do things with Postgresql on FreeBSD. If manually starting/stopping the services, it is important to stop tomcat, restart postgres, and then restart tomcat, in that order.

  • If you change the password in the webapps directory and recompile therein, tomcat won’t actually see your changes. It’s bad practice to work directly in the webapps directopry anyway. You will have to re-war (jar cvf * in thepub/), copy the war to some other location like /tmp, stop tomcat, delete the old webapps/thepub and webapps/thepub.war (if you dont stop tomcat, deleting these will be a no-op, and they’ll magically reappear), and finally (with tomcat still stopped), copy in the new war. Then restart tomcat, access the page, and it will un-war the updated archive.

Ik ben niet liever van Dhr. Eggers

A Reader’s Manifesto

 steal compass, drive north, disappear...