[Aimmath-commit] AIM/doc installwin.html,NONE,1.1.2.1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/aimmath/AIM/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv25298/doc

Added Files:
      Tag: develop_2_1
	installwin.html 
Log Message:
Instructions for installation under Windows

--- NEW FILE: installwin.html ---
<html>
<head>
 <title>Installing AiM under Windows</title>
</head>
<body>
<h1>Installing AiM under Windows</h1>

These are instructions for installing and configuring AiM. Installation
has been tested with Windows 2000 and Windows XP.

<h2>License terms</h2>

AiM relies on various external components, such as 
<a href="http://www.maplesoft.com">Maple</a>, 
<a href="http://java.sun.com">Java</a>, 
the <a href="http://jakarta.apache.org/tomcat/">Tomcat</a> web server, 
<a href="http://hutchinson.belmont.ma.us/tth/">TtH</a> for LaTeX-to-HTML conversion, 
the <a href="http://www.servlets.com/cos/index.html">com.oreilly.servlet</a> support classes,
and the <a href="http://www.interlog.com/~tcharron/blat.html">blat</a> mailer.
The license terms for these components can be found on their webpages.

The Maple and Java source code for AiM itself is free software; you
can redistribute it and/or modify it under the terms of the GNU <a
href='http://www.gnu.org/licenses/gpl.html'>General Public
License</a>, as distributed by the <a href='http://www.fsf.org'>Free
Software Foundation</a>; 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.

<h2>Maple</h2>

You will need Maple version 7 or 8. Simply follow Maple's default installation
procedure. 

If you want to use AiM for actual teaching (rather than just checking
it out) you will need a Maple license that allows you to make the
program available over the web. If you have a campus site license,
then this is not an issue. If you do not have such a license, or are
unsure of the type of license that your campus has, then you should
contact <a href='mailto:in...@ma...'>Waterloo Maple</a>
directly to ensure that you are complying with your license terms. If
you have any complex discussions about licensing issues then I (<a
href='mailto:N.P...@sh...'>Neil Strickland</a>)
would appreciate a copy. Waterloo Maple are aware of AiM and are
generally supportive. Our main contact there has been <a
href='dmc...@ma...'>Darren McIntyre</a> (but you should
email <a href='mailto:in...@ma...'>in...@ma...</a> in
the first instance).

<h2>Java</h2>

You will need to download the JDK (Java development kit) from <a
href="http://java.sun.com">java.sun.com</a>. The current version is
<a href="http://java.sun.com/j2se/1.4.2/download.html">J2SDK 1.4.2</a> 
but any other version should work just as well. Note that
you need the full JDK, not just the runtime environment JRE. It comes
with an automatic installer. Just follow the default procedure. It will
install the JDK into the folder C:/j2sdk1.4.2.

<h2>Tomcat</h2>

You will need the Jakarta Tomcat 4 server from <a
href="http://jakarta.apache.org">jakarta.apache.org</a>. Download and run 
the automatic installer for 
<a href="http://apache.towardex.com/jakarta/tomcat-4/binaries/tomcat-4.1.24.exe">
tomcat 4.1.24</a>. When the installer offers you to change the default installation
location, I recommend you choose C:\Tomcat because it will be easier to find than
the default location deep inside the C:\Program Files folder. Towards the end
of the installation you will also be asked for the port number, you can simply
leave it at the default 8080. You will be able to create an admin account on the
Tomcat manager.

<h2>AiM</h2>

You are now finally ready to install AiM itself by following the following steps.
<ol>
<li>
Download the latest file release (with a name starting with complete) from 
<a href="http://sourceforge.net/projects/aimmath/">SourceForge</a> and unzip 
it into a subdirectory of the 
C:\Tomcat\webapps\
directory. You can choose any name for this subdirectory. Below we will assume that
you chose the name "AiM". 
If you chose something different, simply replace "AiM" by 
your choice in all filenames and URLs below. You might for example want to change a 
different name if you already have an AiM server installed in the folder 
AiM and want
to run the new installation in parallel.
</li>
<li>
Change directory to C:\Tomcat\webapps\AiM\WEB-INF\maple.
Open the file ManualConfig.dist in notepad or you 
favourite texteditor. In this file you can make changes to the default configuration. You
should then save it under the name ManualConfig.mpl. 
You will want to uncomment
the line Config['SMTPServer'] := "smtp.york.ac.uk": and
replace the server name by the name of your local mail server.
Also, if you chose a directory other than AiM 
you should uncomment the line Config['TomcatContext'] := "AiM": 
and replace AiM by the name you chose. 
</li>
<li>
Now start Maple, and issue the command read(`AutoConf.mpl`);
This will use the settings you made in ManualConfig.mpl but otherwise will try to
find out all the necessary configuration information automatically.
If it complains of any problems, you may wish to set 
waffle := true and run it again
to get a more verbose report. The output is saved in the file 
autoconf.log as well as being
printed on the terminal. Using this information you can then review the
settings in ManualConfig.mpl and make the
necessary changes before reading in AutoConf.mpl again. You can iterate
this procedure as often as you like until you get an installation without
error messages.
</li>
<li>The installation is complete. Now start your Tomcat server. The Tomcat installation will have installed a shortcut
"Start Tomcat" for this purpose in the Start menu.
</li>
<li>
Point your webbrowser at the
URL of the AiM server. This will be something like http://localhost:8080/AiM/admin.html,
where you may have to replace AiM by the name of the subdirectory of the 
Tomcat/Webapps/
directory into which you unzipped AiM.
You should click on 'Zone login' to log on as the administrator (with empty
 password). After logging in, you can set a password, create new
 subjects and so on.
</li>
</ol>

<h2><a name="trouble">Troubleshooting</a></h2>

If the Alice servlet manages to start up, it will then check its
configuration, ask Maple to calculate 2+2, and ask TtH to translate a
minimal tex file. If any of these things fail, it will display an
error report when you try to log in as the administrator; this will
hopefully be self-explanatory. If necessary, you can ask for help in the
<a href="http://aimmath.sourceforge.net/mod/forum/index.php?id=2">AiM Forums</a>.

Some other kinds of errors may give you a Java stacktrace in your
browser, looking something like this:

<pre>
2002-08-18 03:45:27 StandardWrapperValve[Alice]: Servlet.service()
 for servlet Alice threw exception
javax.servlet.ServletException: Unexpected output while initializing
 new AiM process:
Error, unable to read `AliceServer.mpl`

	at Alice.initMaple(Alice.java:579)
	at Alice.doPost(Alice.java:352)
	at javax.servlet.http.HttpServlet.service(HttpServlet.java:760)
        &lt;continued for many lines&gt;
</pre>
</font>
Note that this includes the line number in the source file Alice.java
where the error occurred.  The top of the stacktrace is often
reasonably comprehensible.  
<p/>
With other kinds of problems you may see a message like 
<font color='red'>Servlet Alice is unavailable</font> in your browser.  
This means that Tomcat started successfully but Alice did not.  You
should look at the most recent Tomcat log file
<font color='green'>Tomcat\logs\log.YYYY-MM-DD.txt</font>, 
and search backwards from the end for the string
&quot;unavailable&quot;. Just above this, you should find a
stacktrace, and the top of the stacktrace may be informative.
<p/>
If you see nothing at all in the browser, then Tomcat itself failed to
start.  Some possible reasons:
<ul>
 <li>Tomcat had not shut down properly when you tried to restart it.
  I have found it safest to shut down twice (which gives an error
  message on the second attempt) before restarting.
 </li>
 <li>There may be another web server (such as Apache or IIS) already
  listening on port 8080 or whichever port you chose for Tomcat.  
  This will give a message saying 
  <font color='red'>java.net.BindException: Address already in
  use</font> in the log file.  You should either shut down the other
  server, or change the port that Tomcat is listening and also set 
  <font color='green'>Config['TomcatPort']</font>
  in <font color='green'>ManualConfig.mpl</font> to specify a
  different port.
 </li>
 <li>The message <font color='red'>Catalina.stop:
  java.net.ConnectException: Connection refused</font> just means that
  you tried to stop Tomcat when it was already stopped; this can
  safely be ignored.
 </li>
</ul>

<hr>
Last modified by Gustav Delius on 15/07/03

</body>
</html>