Install Cheat Sheet for WebMan: A Basic RefEntry Servlet Mark Craig, 370-68-2121 ------------------------------------------------------- This install cheat sheet is for impatient people like me who want to start installation right away without reading any documentation. Maybe you already extracted the files, but then got a little stuck because it was not clear what to do next. This file should help a little. If you really want to know what I did, you probably should read the project doc, under /docs. (You did install the doc, didn't you?) Contents ------------------------------------------------------- Ia. Installing on Linux Ib. Installing on Windows Ic. Installing on MacOS X II. Uninstalling Ia. Installing on Linux (Seems to Work on Solaris, Too.) ------------------------------------------------------- The examples in the following steps work if you are running Bash, the default shell on Linux. To run Bash in a terminal window, enter "bash" at the shell prompt. 1. Make sure you have a Java[tm] Development Kit 1.4 or later installed. If you do not have a recent JDK, download one from http://java.sun.com. If you do not know which version you have, then check. For example, if you installed 1.4.1: bash$ java -version java version "1.4.1-rc" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-rc-b19) Java HotSpot(TM) Client VM (build 1.4.1-rc-b19, mixed mode) 2. Do not begin the installation before reading this: The only pack you *must* install is the servlet .war file. This is the case so you do not have to reinstall Ant, HttpUnit, or Tomcat if you have it already. If you want to use the servlet .war file, you must have a servlet container such as Tomcat. So if you are missing a servlet container, install the Tomcat pack at least. If you want to do any development, such as write your own RefEntry documents and build a servlet, then you need Ant and HttpUnit. Unless you have Ant and HttpUnit already installed, take these packs as well. If you are reading this file, perhaps you already decided you do not want the docs. Fine. When you send me questions that are answered in the docs, I'll be sending you RTFM pointers ;-) 3. Run the self-extracting installer, refentry-installer.jar. For example: bash$ java -jar /refentry-installer.jar Follow the instructions, based on what you decided to install. If you run this in a terminal without starting X, the installer generates an unexpected exception on startup and exits, displaying the stack trace. This particular installer does not work without a GUI, so start X before you run it. You can go back to your terminal window after you install it. 4. Set JAVA_HOME to point to the JDK if it is not set already. For example, to check JAVA_HOME, then set it: bash$ echo $JAVA_HOME bash$ which java /bin/java bash$ export JAVA_HOME= If you are on a network where multiple Java SDK versions are maintained side by side, finding JAVA_HOME might be much less straightforward. At work, one of my install testers had to follow three symbolic links before she finally got to the directory where Java was actually physically installed. 5. Source the refentry.profile file in the directory where you installed the bits. For example: bash$ source /refentry.profile The refentry.profile file is written for Bash. Hack the file yourself if you want to use a different shell. 6. Copy the servlet .war file to the Tomcat webapps directory. bash$ cp /refentry.war $CATALINA_HOME/webapps/ CATALINA_HOME designates the Tomcat servlet container installation directory. 7. Start the Tomcat servlet container. bash$ $CATALINA_HOME/bin/startup.sh This starts the Tomcat servlet container in the background. 8. Browse http://localhost:8080/refentry and you should see the default page of the RefEntry servlet. If everything went well and you want to develop your own RefEntry servlet with your own documentation, you might want to add two lines in your .bash_profile to set JAVA_HOME and to source refentry.profile at startup. If you want to stop Tomcat, the command is: $CATALINA_HOME/bin/shutdown.sh Ib. Installing on Windows ------------------------------------------------------- If you install this on Windows, you might want to ask yourself why you are still using Windows for development. If you do need Windows for something, there might still be room on your system for a Linux partition. You can even put Windows as the system by default when you dual boot. Your grandmother will never notice the difference. 1. Make sure you have a Java[tm] Development Kit 1.4 or later installed. If you do not have a recent JDK, download one from http://java.sun.com. If you do not know which version you have, then check. For example, if you installed 1.4.1: C:\Windows>java -version java version "1.4.1_01" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01) Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode) 2. Do not begin the installation before reading this: Avoid installing in a folder with a name longer than 8 characters. This software relies on environment variables rather than the Windows registry. If you use long folder names, you have to figure out how to translate them when setting the environment variables. For example, C:\Program Files\RefEntry may become C:\Progra~1\RefEntry. The only pack you *must* install is the servlet .war file. This is the case so you do not have to reinstall Ant, HttpUnit, or Tomcat if you have it already. If you want to use the servlet .war file, you must have a servlet container such as Tomcat. So if you are missing a servlet container, install the Tomcat pack at least. If you want to do any development, such as write your own RefEntry documents and build a servlet, then you need Ant and HttpUnit. Unless you have Ant and HttpUnit already installed, take these packs as well. If you are reading this file, perhaps you already decided you do not want the docs. Take them anyway. Disk is cheap. 3. Double-click the self-extracting installer, refentry-installer.jar. Follow the instructions, based on what you decided to install. 4. If you are using Windows 95 or 98, copy the \ant folder to a location with a very short path name such as C:\ant. Ant uses a startup script that suffers from DOS-related limitations. 5. Adjust and set the environment variables in \refentry.bat. How you do this depends on your version of Windows. Windows command.com shell cannot handle long file and folder names. You must therefore declare environment variables using the 8+3 MS-DOS names. In other words, if you install the software in C:\Program Files\RefEntry, then you must change this to something like C:\Progra~1\RefEntry in refentry.bat and in autoexec.bat. When using Windows 2000, you can set environment variables for your account, and Windows puts them in the registry. Set the environment variables you need from Control Panel > System > Advanced > Environment Variables, based on the packs you installed. When using Windows 95 or 98, you can call a script from C:\autoexec.bat which sets the environment at startup. You can also add the environment variables you need, based on the pack you installed, directly to autoexec.bat. If you use ANT_HOME, note that it must be a very short path name on Windows 95 or 98. 6. At this point, if you are using Windows 95 or 98, you must reboot. 7. Copy \refentry.war file to the \tomcat\webapps folder. 8. Start the Tomcat servlet container. With Windows 95 and 98, you must increase the memory available in the command shell to be able to start Tomcat. To increase the memory available, click the Properties icon, then in the MS-DOS Prompt Properties window, select the Memory tab and set Initial environment to 4096. Next, click OK, and type exit to leave the MS-DOS Prompt command shell. Restart the MS-DOS Prompt command shell for the change to take effect. C:\Windows>%CATALINA_HOME%\bin\startup This starts the Tomcat servlet container in the background. 9. Browse http://localhost:8080/refentry and you should see the default page of the RefEntry servlet. If you want to stop Tomcat, the command is: %CATALINA_HOME%\bin\shutdown Ic. Installing on MacOS X ------------------------------------------------------- I'll write this section if you send me the hardware to try it ;-) II. Uninstalling ------------------------------------------------------- 1. If you are running the version of Apache Tomcat installed with this software, then stop the Tomcat server. (Linux) $ $CATALINA_HOME/bin/shutdown.sh (Windows) C:\Windows>%CATALINA_HOME%\bin\shutdown 2. If you added any environment variables to your environment manually, then retrace your steps to remove them manually. 3. If you are using Windows 95 or 98 and you copied Ant to some short path like C:\ant, then delete the folder. 4. Run the self-extracting uninstaller, uninstaller.jar. (Linux) $ java -jar /Uninstaller/uninstaller.jar (Windows) Double-click /Uninstaller/uninstaller.jar. You may delete any remaining files at this point. ------------------------------------------ WebMan: A Basic RefEntry Servlet Copyright (C) 2002-2003 Mark Craig This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA