Installing JSPWiki on Debian
Note: this documentation is fairly old, and may be out-of-date. I no longer use JSPWiki.
These notes should be generally applicable both to Debian woody and Debian sarge. My JSPWiki install broke on upgrade to etch (Tomcat issues, I guess), and I gave up and converted to Mediawiki instead. So, these notes don't (necessarily) apply to newer versions of JSPWiki.
Java 1.4 on Woody
JSPWiki requires tomcat4, and apparently only works well with Java 1.4 (not Java1.3). Unfortunately, Java 1.4 isn't available as a Debian package for 'woody'. So, I had to go through a whole mess of work to get 1.4 onto the machine and set up so that all of the Debian packages would recognize it. I roughly followed the procedure as documented in the Debian Java FAQ http://www.debian.org/doc/manuals/debian-java-faq/ch11.html#s11.2.
First, I went to java.sun.com and downloaded the j2re1.4 and j2sdk1.4 packages for Linux. Note: you do NOT want the version bundled with NetBeans. That's the default download, and it's 90+MB of crap. What I got was labled "Download J2SE v 1.4.2_03", and then I got the JRE and SDK. It turns out that I only needed the SDK download, since it includes the JRE (this actually makes sense, though).
I copied the file onto daystrom and then did:
sh ./j2sdk-1_4_2_03-linux-i586.bin
This created the j2sdk1.4.2_03/ directory. As root, I changed ownership of the entire directory to root:root and moved it to /opt/local/lib.
Then, I started making dummy replacement packages to satisfy Debian dependencies. The java-common package from 'sarge' has in its doc directory a set of Debian control files that can be used by equivs to build the dummy .deb files (note that the control files can be found in /usr/share/doc/java-common/dummy-packages once you have installed the java-common package):
equivs-build java2-runtime-dummy.control equivs-build java-compiler-dummy.control
Once I had the .deb files, I installed them:
dpkg --install java2-runtime-dummy_1.0_all.deb dpkg --install java-compiler-dummy_1.0_all.deb
Then, I had to update the alternatives so that some things could be found:
update-alternatives \ --install /usr/bin/java java /opt/local/lib/j2sdk1.4.2_03/bin/java 500 \ --slave /usr/share/man/man1/java.1 java.1 /opt/local/lib/j2sdk1.4.2_03/man/man1/java.1 update-alternatives \ --install /usr/bin/javac javac /opt/local/lib/j2sdk1.4.2_03/bin/javac 500 \ --slave /usr/share/man/man1/javac.1 javac.1 /opt/local/lib/j2sdk1.4.2_03/man/man1/javac.1
Actually, this didn't work the first time, because I goofed up what I typed in, and used "re" instead of "sdk" in the path. This left around garbage alternatives which were unfortunately at the same priority as the ones I was trying to add (500).
So, first, I removed the garbage alternatives:
update-alternatives --remove javac /opt/local/lib/j2sdk1.4.2_03/bin/javac update-alternatives --remove java /opt/local/lib/j2sdk1.4.2_03/bin/java
Once I did this, what I had left looked like this:
/home/pronovic/tmp/java1.4# update-alternatives --display java
java - status is manual.
link currently points to /opt/local/lib/j2re1.4.2_03/bin/java
No versions available.
/home/pronovic/tmp/java1.4# update-alternatives --display javac
javac - status is manual.
link currently points to /opt/local/lib/j2re1.4.2_03/bin/javac
No versions available.When I used the proper --install commands, the new "sdk" paths were listed as alternatives, but weren't copied to the link. To fix that, I used:
update-alternatives --auto java update-alternatives --auto javac
That set everything to point at the right place.
Once everything was installed, I just ran these commands as root:
java -version javac
The FAQ suggests doing this to make sure that any runtimes directories or files created the first time the exectuable is used have the right ownership, etc.
Tomcat installation
Tomcat installed easily enough:
/root# apt-get install tomcat4
Reading Package Lists... Done
Building Dependency Tree... Done
The following extra packages will be installed:
j2re1.3 j2se-common libregexp-java libservlet2.3-java libtomcat4-java libxerces2-java
The following NEW packages will be installed:
j2re1.3 j2se-common libregexp-java libservlet2.3-java libtomcat4-java libxerces2-java tomcat4
0 packages upgraded, 7 newly installed, 0 to remove and 0 not upgraded.
Need to get 15.9MB of archives. After unpacking 42.1MB will be used.
Do you want to continue? [Y/n] However, it wasn't quite sure where to find Java since I was using a custom location. I had to edit its /etc/default/tomcat4 file and set:
JAVA_HOME="/opt/local/lib/j2sdk1.4.2_03"
Then, in /etc/tomcat4/server.xml, I commented out the "Tomcat Manager Context", since I've known it to give me errors. I also modified the standard tomcat HTTP connector to be on port 8080 (more standard) rather than 8180.
After that, I restarted tomcat using the tomcat4 init.d script, and tested that the base URL worked:
http://localhost:8080/
I also checked the logs in /var/log/tomcat4 to look for any problems.
JSPWiki installation
There is a Debian package for JSPWiki, but it's only in 'sarge'. However, since it depends only on things that are in 'woody' (other than Java 1.4), it should run fine there.
dpkg --install jspwiki_2.0.52-4_all.deb
Make sure that this soft link really exists:
/etc/tomcat4/policy.d/05jspwiki.policy -> /etc/jspwiki/tomcat.policy
If it doesn't, reinstall the package. It seems to be created only on the second try.
Once the package was installed, I bounced tomcat to make sure the new definitions existed, and then checked the default JSPWiki URL:
http://localhost:8080/JSPWiki
This took a little while the first time (because all of the pages needed to be compiled) but after that worked fine.
Getting rid of :8080 in URLs
When I originally got the Wiki up and running, I intended to make things work so that the :8080 port was not required on the tomcat Wiki URLs. However, I had some serious problems with the libapache-mod-jk Apache connector that comes with Debian woody. I originally spent a few hours screwing around with it and finally gave up when it always just crashed rather than mapping the URL.
Later on (a few days later, when my bloodpressure had come down) I spent some more time on it, and eventually made it work. As far as I can tell, my problem was that for some reason, when I installed the libapache-mod-jk package, it didn't put a LoadModule directive in Apache configuration. I guess either it didn't work right or for some reason I didn't allow the package to make its requested changes to httpd.conf. Or, maybe I'm just nuts.
Anyway, it turned out to be not that difficult to get the connector working. First, install the package:
daystrom:/root# apt-get install libapache-mod-jk
Reading Package Lists... Done
Building Dependency Tree... Done
The following NEW packages will be installed:
libapache-mod-jk
0 packages upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 51.5kB of archives. After unpacking 233kB will be used.
Get:1 http://security.debian.org woody/updates/contrib libapache-mod-jk 3.3a-4woody1 [51.5kB]
Fetched 51.5kB in 0s (54.7kB/s)
Selecting previously deselected package libapache-mod-jk.
(Reading database ... 28835 files and directories currently installed.)
Unpacking libapache-mod-jk (from
.../libapache-mod-jk_3.3a-4woody1_i386.deb) ...
Setting up libapache-mod-jk (3.3a-4woody1) ...Then, in /etc/tomcat4/server.xml, uncomment (enable) this connector:
<!-- Define an AJP 1.3 Connector on port 8009 -->
<!-- Debian specific note: If you enable this connector you must disable
it in the tomcat (Tomcat 3.x) package. The package for the Apache
connector module is libapache-mod-jk -->
<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
port="8009" minProcessors="5" maxProcessors="75"
acceptCount="10" debug="0" address="127.0.0.1"/>This is the AJP13 "listener" that services requests from Apache to Tomcat. If it's not enabled, Apache and Tomcat have no way to talk.
Note: if you're having problems, you may want to change the debug value from "0" to "9". You may also need to change JkLogLevel to debug in httpd.conf to make this work (see below). Either way, look in /var/log/apache/mod_jk.log.
Then, go through /etc/tomcat/jk/workers.properties and make changes as needed. In particular, I had to modify these lines:
workers.java_home=/opt/local/lib/j2sdk1.4.2_03 worker.list=ajp13
I also commented out the unused AJP12 worker and load balancer worker definitions. Everything else I left alone.
If for some reason, you do not have a LoadModule directive elsewhere for mod_jk.so, add one at the top of this section:
LoadModule jk_module /usr/lib/apache/1.3/mod_jk.so
In newer versions of Apache, you can make this happen using:
/usr/sbin/apache-modconf apache enable mod_jk
I think that installing the connector should just make this happen, but it doesn't seem to.
When you're done with this, remove these package-generated lines at the bottom of /etc/apache/httpd.conf, if they exist:
<IfModule mod_jk.c> # The following line is for apacheconfig - DO NOT REMOVE! JkWorkersFile /etc/tomcat/jk/workers.properties Include /var/lib/tomcat/conf/mod_jk.conf </IfModule>
I replaced the package-generated lines with my own configuration:
# By-hand configuration for libapache-mod-jk AddModule mod_jk.c JkWorkersFile /etc/tomcat/jk/workers.properties JkLogFile /var/log/apache/mod_jk.log JkLogLevel info JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " JkMount /JSPWiki ajp13 JkMount /JSPWiki/* ajp13
The AddModule line might not be required. If you get an error about "mod_jk already added" them you can remove it.
The mod-jk HOWTO (which comes with the Debian package in the doc directory) implies that you can get tomcat4 to automatically generate some of this information for you,
- but I couldn't get it to work. Basically, what you're doing is setting up explicit
mappings for URLs that Apache is supposed to pass off to tomcat4.
Once this is all done, restart apache and tomcat4, and the new "cleaner" URL should just work:
http://localhost/JSPWiki
If it doesn't, check the tomcat and apache directories for errors in the log files.
Setting up Additional Wikis
By default, the installing the JSPWiki package results in one Wiki, at the URL mentioned above (/JSPWiki). However, it's possible to run a single install of the JSPWiki software and support two or more different Wiki URLs (which will be completely independent of one another). That's nice, because I should only have to upgrade one thing at a time.
In theory, this is pretty easy. However, Debian's setup for webapps makes it somewhat challenging. I've decided that the simplest way to do this is to have a "default" Wiki called JSPWiki, then I can add on other Wikis with soft links. This seems to work best because everything goes to hell if you try to get rid of the default JSPWiki web application.
Here are the steps I followed in order to add an additional Wiki. These notes assume I added a Wiki called OtherWiki.
First, copy the actual Wiki contents. We'll use the original Wiki as a starting point:
cd /var/lib/jspwiki cp -R default other chown -R tomcat4:root other
Then, create the OtherWiki webapp for tomcat to find:
cd /usr/share/java/webapps ln -s JSPWiki OtherWiki
Then, copy the templates directory:
cd /usr/share/java/webapps/JSPWiki/templates cp -r default other
Next, create a new other.properties file in /etc/jspwiki. Edit all of the properties to your liking. In particular, be sure to change these properties:
jspwiki.applicationName = OtherWiki jspwiki.fileSystemProvider.pageDir = /var/lib/jspwiki/other jspwiki.basicAttachmentProvider.storageDir = /var/lib/jspwiki/other jspwiki.templateDir = other log4j.appender.FileLog.File = /var/log/tomcat4/other.log
BE SURE to leave the pageProvider property as FileSystemProvider initially, until after the first time the Wiki has been accessed. Some bug prevents certain things from working otherwise.
Next, create the application definition for use by tomcat:
cd /etc/jspwiki cp jspwiki.xml logomachy.xml
Edit logomachy.xml and change "JSPWiki" to "OtherWiki" as appropriate. Also, add one line to the file:
<Parameter name="jspwiki.propertyfile" value="/etc/jspwiki/other.properties" override="false"/>
Then, create a soft link to the file so Tomcat knows about it:
cd /usr/share/tomcat4/webapps ln -s /etc/jspwiki/logomachy.xml logomachy.xml
Then, edit /etc/jspwiki/tomcat.policy and add four new lines to it:
permission java.io.FilePermission "/var/lib/jspwiki/other", "read"; permission java.io.FilePermission "/var/lib/jspwiki/other", "write"; permission java.io.FilePermission "/var/lib/jspwiki/other/*", "read"; permission java.io.FilePermission "/var/lib/jspwiki/other/*", "write";
(You can get rid of the duplicate grants at the same time, if you wish. I don't know why they're in the file at all.)
Finally, make sure to add a mapping in the mod_jk section at the bottom of /etc/apache/httpd.conf for OtherWiki:
JkMount /OtherWiki ajp13 JkMount /OtherWiki/* ajp13
Then, restart apache and tomcat with the init scripts, and when they come back up, all of these URLs should work:
http://localhost:8080/JSPWiki http://localhost:8080/OtherWiki http://localhost/JSPWiki http://localhost/OtherWiki
Once you know both Wikis work, you probably want to change the page provider, so that page history gets stored:
jspwiki.pageProvider = VersioningFileProvider
The RCSFileProvider has some issues, so it seems best to stick with the VersioningFileProvider. Bounce tomcat after you make the changes, to be sure they worked.
Look-and-feel Customization
JSPWiki supports a templating system to customize look-and-feel. That's what the jspwiki.templateDir property controls. You just make a copy of the original default directory and customize whatever you want among the available templates.
There are also some other customizations available. For instance, you can add graphics, override JSPs in the web application (i.e. files in the main JSPWiki directory), and add properties to the config file.
I took my Wiki template from the MRG template on http://www.jspwiki.org. This template includes a whole set of files for the template directory plus two .jsp files (UserPreferences.jsp and PrintFriendly.jsp) and some graphics. I redid some of the graphics and customized the CSS (style sheet), but other than that, I pretty much left the template alone.
This template requires a new jspwiki.specialPage.SiteLogoRedirect property in the property file for each Wiki that will use it (it just goes near the other specialPage properties).
In order to test, I copied my new template files into the JSPWiki webapp directory appropriately, and then changed the templateDir for one of the active Wikis and then bounced tomcat. If you're doing this, and the page just doesn't seem to pick up your changes, stop tomcat, blow away the appropriate cache directory in /var/cache/tomcat4 and then restart tomcat. That usually takes care of the problem.
Monitoring Changes to the Wiki
I'm not quite sure yet what to expect with this Wiki. So, I've set up a script to send me daily emails about what changed in the Wiki. That way, I'll be able to see how often changes are made, and I'll be able to roll back changes if I don't like them (the VersionedFileProvider makes that easy).
I did this through a new "Recent Changes Daily" Wiki page, which is exactly the same as "Recent Changes" except it only shows changes for the last day or so. I run a cron job to grab the contents of this page, dump it to text with w3m -dump, and mail myself the results. It's crude, but it will help me keep on top of things.