Java example - README.xml

<TD>Path to the plugin directory </TR> <TR> <TD>webmail.auth.path <TD>Path to the authenticator directory </TR> <TR> <TD>webmail.data.path <TD>Path to WebMail libraries </TR> <TR> <TD>webmail.template.path <TD>Path to language dependent template files </TR> <TR> <TD>webmail.storage <TD>Set this to net.wastl.webmail.storage.simple.SimpleStorage for the simple storage. Other storage methods might come in the future</TD> </TR> </TABLE> <NOTE> Don't forget to set the correct permissions on the WebMail directory. All subdirectories must be readable by the user running the Servlet engine. Additionally the <CODE>webmail.data.path directory (usually called data/) must be writeable. </NOTE> </SUBSUBSECTION> <SUBSUBSECTION name="Installation for Apache JServ" id="install:servlet:jserv"> JServ is the old Apache Servlet engine for Servlet API 2.0. At the moment, it is probably the Servlet engine that is most common. The requirements for the JServ installation are that you have a running Apache together with a running Apache JServ. As of WebMail 0.7.5, a generic Apache JServ installation script is provided that can be used to add the necessary configuration options to Apache and JServ. Nonetheless you will need to have a running servlet environment. This script is called <CODE>bin/install.sh. Just invoke it with no parameters. It will try to determine your configuration and ask you whether the guessed values are correct. You will be prompted for confirmation before each step. </SUBSUBSECTION> <SUBSUBSECTION name="Installation for Tomcat" id="install:servlet:tomcat"> Requirements: <LIST> <ITEM>Apache webserver <ITEM>Tomcat from the Apache Jarkarta Project <ITEM>mod_jk from the Apache Jarkarta Project (mod_jserv will probably work also with some modifications)</ITEM> </LIST> <NLIST> <ITEM>Modify web.xml file
There is a web.xml file already provided for WebMail in the WEB-INF directory. Please modify the pathnames therein to reasonable values for your configuration. </ITEM> <ITEM>Modify Tomcat configuration: In the tomcat server.xml file add the following entry to the <CODE><ContextManager> element:
 <CODE> <Context path="/webmail" docBase="/path/to/webmail-0.x.x" crossContext="true" debug="0" reloadable="false" trusted="false" > </Context> </CODE> Tomcat will create a mod_jk configuration file automatically from this entry. However the generated file is not sufficient for WebMail as WebMail doesn't use the default directory structure proposed by the Servlet API 2.2. Therefore a second modification is necessary: </ITEM> <ITEM>Modify Apache configuration: In the httpd.conf file from Apache add the following two entries after the entry for the JkWorkersFile and the Include for tomcat's automatic configuration: <CODE>JkMount /webmail/WebMail ajp12
<CODE>JkMount /webmail/WebMail/* ajp12
(if you are using AJP protocol 1.3 please change ajp12 to ajp13) </ITEM> <ITEM>Set permissions on WebMail data directory Please set the permissions on the WebMail <CODE>data/ directory so that the user running Tomcat has write access to it. It is also possible to specify a different directory in <CODE>web.xml. </ITEM> <ITEM>restart Tomcat and Apache and see in Tomcat's stdout.log whether WebMail is starting.</ITEM> </NLIST> </SUBSUBSECTION> <SUBSUBSECTION name="RedHat Installation" id="install:servlet:redhat"> Installation on RedHat systems should be as easy as possible: You need to have a running Apache installation. Install the following RPM packages (you can find them on the WebMail homepage at <A href="http://jwebmail.sourceforge.net">http://jwebmail.sourceforge.net) in the following order: <LIST> <ITEM>JDK 1.2.2 (or greater) - this can be found at the Sun JDK 1.3 for Linux download page <ITEM>Apache JServ - an RPM can be found on most RedHat mirrors and on the WebMail homepage <ITEM>WebMail </LIST> You will then have a running WebMail Servlet at <CODE>http://yourhost/webmail/webmail when you restart your Apache webserver. Please don't forget to change your configuration by going to <CODE>http://yourhost/webmail/webmail/admin and logging in with "Secret" (and don't forget to change the password!). <NOTE>This installation instruction (and the RPMs found on the WebMail homepage) are for RedHat 6.2 only. That means they may or may not work on RedHat versions lower or greater than 6.2. If you don't manage to install WebMail with the RPM, please try the binary release and run bin/install.sh for the generic configuration.</NOTE> </SUBSUBSECTION> <SUBSUBSECTION name="Debian Installation" id="install:servlet:debian"> Installation on Debian woody is as simple as on RedHat. You will have to install Apache JServ with apt-get (<CODE>apt-get install jserv will install the necessary packages) and then install the WebMail package (with <CODE>dpkg --install webmail*.deb).
You will then have a running WebMail Servlet at <CODE>http://yourhost/webmail/webmail when you restart your Apache webserver. Please don't forget to change your configuration by going to <CODE>http://yourhost/webmail/webmail/admin and logging in with "Secret" (and don't forget to change the password!). You might want to install a more up-to-date JDK to run WebMail properly, I will try to make a Debian package available for JDK 1.2.2, but you can also simply install a tar of the most up-to-date JDK and update the links in <CODE>/etc/alternatives: <LIST> <ITEM>update-alternatives /usr/bin/java java /usr/lib/<YOUR_JDK>/bin/java 130 <ITEM>update-alternatives /usr/bin/javac javac /usr/lib/<YOUR_JDK>/bin/javac 130 <ITEM>update-alternatives /usr/bin/jar jar /usr/lib/<YOUR_JDK>/bin/jar 130 </LIST> Replace <YOUR_JDK> part with the path of your JDK installation (e.g. jdk1.3) and the "130" with the version information (130 is for jdk 1.3, jdk1.2.2 would get 122). <NOTE>This installation instruction (and the DEBs found on the WebMail homepage) are for Debian woody only. That means they may or may not work on Debian potato and slink</NOTE> </SUBSUBSECTION> </SUBSECTION> <SUBSECTION name="Storage Methods" id="install:mysql"> By default, WebMail uses a so-called SimpleStorage to store user and system configurations, i.e. the data is stored in separate XML-files. <NOTE> WebMail used to have a database storage in a 0.7 prerelease. Unfortunately this has become obsolete with the XML user model and needs to be re-implemented. I plan to do this in one of the next releases </NOTE>  </SUBSECTION> </SECTION> <SECTION name="Configuration" id="config"> WebMail has an administration interface which allows you to perform several runtime administration tasks, including: <LIST> <ITEM>Changing all configuration settings <ITEM>Shutting down the server properly <ITEM>Adding, deleting or editing WebMail virtual domains <ITEM>Adding, deleting or editing WebMail users <ITEM>Getting status information </LIST> <SUBSECTION name="WebMail Administrator Plugin" id="config:admin"> <SUBSUBSECTION name="Connecting" id="config:admin:connecting"> You can connect to the administration interface with your browser by simply entering the URL <CODE>http(s)://webmail_server:port/admin in the address field of your browser. (set http/https and replace webmail_server and port with the correct values; port is usually port 6789 after the first start on a standalone server; on a servlet installation you will very likely have to add the WebMail mountpoint before the <CODE>/admin). You'll be presented the administrator's login screen then. Enter the password there (on first startup the password is "Secret") and click the login button. You should see the system settings form then. </SUBSUBSECTION> <SUBSUBSECTION name="System Settings" id="config:admin:system"> The first page gives you a list of WebMail system variables and their values. You can change any variables you like (there is a short description for each of them) and then hit the submit button on the bottom of the page. There are basically 4 kinds of input fields (although you will probably only recognize 2 on first look): <LIST> <ITEM>simple text input fields <ITEM>drop down selects <ITEM>integer input fields (look like text input fields) <ITEM>password input fields (look like text input fields and show the encrypted password!) </LIST> All of these fields will check whether the value entered is (more or less) correct if you submit the form. <NOTE>Special note on password fields: The password is shown encrypted (Unix crypt()), but if you want to change your password, please enter it in plain text. It will then show up encrypted again, after you hit the submit button (but still be the password you just entered).</NOTE> To shutdown or restart the WebMail server, enter the time in seconds until the action will be performed and hit the appropriate button ("SHUTDOWN" or "REBOOT"). ATTENTION: You will not get anything like an answer after you do this (since you are shutting down the server this is quite difficult) and you will not be asked whether you really want to do this! Most likely you will get a "connection timed out" or "document contains no data" dialog. </SUBSUBSECTION> <SUBSUBSECTION name="WebMail Virtual Domain Support" id="config:admin:vdom"> Virtual Domains in WebMail are a quite new concept (thanks to Oswaldo E. Aguirre M. for the idea). They basically provide the following features: <LIST> <ITEM>users are associated to a domain (even if you only have one domain) <ITEM>each domain can have its own authentication host (if IMAP/POP authentication is used) <ITEM>the administrator of WebMail can impose certain restrictions on users of a WebMail domain. e.g. you can restrict the hosts where users may connect to here</ITEM> <ITEM>each domain has its own default host where the user's primary folder will be found <ITEM>the user's default email address will be set to "user@domain" </LIST> Naturally, with this concept you will need to have at least one domain even if you don't plan to use virtual domains really. The WebMail virtual domain setup form is quite simple and self explanatory, I think. There is one column where you have to enter the domain name, one where you have to enter this domain's default host (user's primary folder host), one for the authenti- cation host (not necessarily the same as the default host), and some fields that control the restrictions for users of this domain. With the checkbox, you can turn on/off host restriction completely, in the allowed hosts column, you can enter a comma-separated list of domains/hosts where users may access IMAP folders (e.g. "wastl.net" would allow them to use "mail.wastl.net" and "pop.wastl.net" while setting it to "mail.wastl.net" would just allow "mail.wastl.net" (and certainly "imap.mail.watl.net") and so on (suffix is matched to say it simple)). </SUBSUBSECTION> <SUBSUBSECTION name="Editing Users" id="config:admin:users"> You can add, edit and delete users from the administration interface (Note that you don't have to create users before they may use WebMail since they get default settings when they first log on authenticating against IMAP, POP or Unix). To create a user, <LIST> <ITEM>enter the user name and the domain in the user field (in the form "user@domain") <ITEM>optionally change all the other fields from the default settings <ITEM>hit the create/edit button on the bottom of the page </LIST> To edit a user, <LIST> <ITEM>select the user in the drop down menu OR enter the user name (with domain) in the short text field</ITEM> <ITEM>edit the user settings <ITEM>hit the create/edit button on the bottom of the page </LIST> To delete a user, <LIST> <ITEM>select the user in the drop down menu OR enter the user name (with domain) in the short text field</ITEM> <ITEM>Hit the delete button </LIST> </SUBSUBSECTION> <SUBSUBSECTION name="Viewing WebMail Status" id="config:admin:status"> Last but not least you can get an overview of currently active sessions with the "view sessions" link. You will get some status information there as well as the possibility to explicitly kill an active session (whatever maybe the reason). Please be careful however with this feature, as you are very likely to kill a session that is currently in use and its user will probably not be very happy about that. The sessions will expire after a configured time anyway. The Administrator Interface is currently available in English only, but the templates are already prepared for translation The system's default language will then be used (determined by the LANG environment setting). I hope the rest is quite self explanatory at the moment, but I'll add some documentation later. </SUBSUBSECTION> </SUBSECTION> <SUBSECTION name="File-Based Shutdown" id="config:admin:shutdown"> You can initiate a WebMail shutdown when you create a file "shutdown" (or whatever you configured) in the data directory with only the admin password in it. This option can be disabled. It is useful in automatic system startup/shutdown. </SUBSECTION> </SECTION> <SECTION name="User Authentication" id="auth"> WebMail supports extended user authentication. At the moment, the following authentication methods are supported: <LIST> <ITEM>SIMPLE: Use WebMail's former authentication method. Password is only checked against the user's configuration. The user may change his password from within WebMail</ITEM> <ITEM>IMAP: Check login/password on a remote IMAP host. WebMail tries to login on a remote IMAP host with the given login and password. If login fails, WebMail doesn't allow access.</ITEM> <ITEM>POP: Same for a POP3 server <ITEM>UNIX: Check login/password using Unix's login facility. login/password are checked against the Unix passwd/shadow files. Note: WebMail must be run as user root to use Unix Authentication</ITEM> </LIST> Changing authentication method can be achieved using the Administration Interface and changing the "AUTH" variable. For IMAP authentication there is an extra configuration variable called "AUTHHOST". </SECTION> <SECTION name="Usage" id="usage"> <SUBSECTION name="General Usage" id="usage:general"> The WebMail daemon listens on whatever port you have configure. Just point your browser愀 URL to http://yourhost:yourport/ and see the login screen. A user will get the password he logs in with the first time. Passwords may be changed by the user in the options dialog. WebMail will try to establish a default connection to the configured default IMAP host with the user ID and password it was given, so it may be useful to use the same ID and password as on the IMAP host. For further information, just click on the "?" at the navigation bar. WebMail should also work with Proxy Servers and other Clients than Netscape Communicator. </SUBSECTION> <SUBSECTION name="Folders" id="usage:folders"> WebMail supports as many IMAP folders on as many different hosts you like. WebMail mailboxes are configured by each user, however the administrator can change the default mailbox for each virtual domain. The default mailbox is the mailbox the user gets on the first login. He can than choose to remove it at any time and also add other mailboxes (the administrator can restrict that in the virtual domain configuration). </SUBSECTION> </SECTION> <SECTION name="Different Languages, Translating WebMail" id="lang"> WebMail supports the usage of different languages on a per user basis. Since v0.6.0 WebMail scans for available languages automatically and adds the corresponding locales to the user's setup dialog ("de" will add the locales "de_DE", "de_AT", "de_CH", ...). To translate WebMail to a new language, please read the file "Translating" in the developers' documentation (source only). </SECTION> <SECTION name="Notes" id="notes"> <SUBSECTION name="WebMail Status" id="notes:status"> WebMail v0.7 is considered BETA, as not all features I want for a "1.0" are yet included. Things I think of are: <LIST> <ITEM>Different XSL stylesheets to convert the WebMail UI to other formats than HTML (perhaps WML for mobile phones)</ITEM> <ITEM>PGP for users using the Cryptix JCE. (http://www.cryptix.org) <ITEM>"Extras" like calendar and so on (will be realized as WebMail Plugins) </LIST> </SUBSECTION> <SUBSECTION name="Changes" id="notes:changes"> See the file "Changes" for a list of changes in the different WebMail releases. </SUBSECTION> </SECTION> <SECTION name="SSL Support (standalone installation)" id="ssl"> Since WebMail 0.7.0, there is finally a free SSL implementation available for Java called ITI-SSL. Installation is simple: <LIST> <ITEM> Fetch the ITI-SSL library from the WebMail homepage for your platform (if there is no binary for your platform, please fetch the source code at the ITI-SSL homepage at http://www-sp.iti.informatik.tu-darmstadt.de/itissl/) </ITEM> <ITEM> Copy the library "libitissl.so" to the WebMail lib/ directory. </ITEM> <ITEM> Start WebMail and possibly enable the SSL support in the administration interface </ITEM> </LIST> However, SSL in WebMail has some drawbacks: <LIST> <ITEM>only works with JDK >= 1.2 (:-( ) <ITEM>is a native library it is no longer platform independent </LIST> If you compile ITI-SSL yourself, please ensure that you use openssl-0.9.4 for compilation because Netscape and IE won't work with WebMail SSL with prior versions. </SECTION> <SECTION name="JDK Installation And Other Java Issues" id="java"> <SUBSECTION name="What is Java" id="java:what"> <NOTE>I'll make it short here as Java is pretty well known and documented. Java is a platform independent, object-oriented (OO) programming language. Java programs are compiled using the JDK Compiler (javac) or other compilers (e.g. IBM jikes). The resulting bytecode is optimized for the Java Virtual Machine (JVM) and still platform independent. The JVM interpretes the previously compiled bytecode and translates it "on the fly" into platform dependent system calls. Therefore a JVM must exist for your platform in order to run Java programs. You'll obviously recognize that Java is an interpreted language similar to Perl or Python. The most sigificant difference to the former two is that Java is precompiled. So Java is a kind of compromise between purely interpreted languages and languages that are compiled to machine code which tries to combine the advantages of both (reliability and speed). As far as i know, this principle is derived from PROLOG. </SUBSECTION> <SUBSECTION name="Where to obtain Java for your platform" id="java:obtain"> The main Java distribution site is http://java.sun.com. You will get the "officially supported" platforms and lots of documentation and additions there. Java distributions for the different platforms: <TABLE> <TR> <TD>Solaris SPARC and x86 </TR> <TR> <TD>Windows: </TR> <TR> <TD>Linux/x86: </TR> <TR> <TD> </TR> <TR> <TD> </TR> <TR> <TD>Linux/PPC: </TR> <TR> <TD>Linux/Alpha: </TR> <TR> <TD>Linux/SPARC: </TR> <TR> <TD>AIX: </TR> <TR> <TD>Macintosh: </TR> <TR> <TD>OS/2: </TR> <TR> <TD>FreeBSD: </TR> </TABLE> </SUBSECTION> <SUBSECTION name="How to install Java properly" id="java:install"> Use your system's standard facility to install the Java packages. Note that the Linux JDK most likely comes as "tar.gz" and not as .rpm or .deb, so you will have to manually install it using tar. On Solaris, the JDK will install in /usr/java1.x/ by default. On Linux, I prefer installing the "tar.gz" in /usr/local and renaming the extracted path to "java1.x". Many distributions, however, will install Java in /usr/lib/java1.x or /usr/lib/jdkxxx. Next, link all programs in the bin/ directory to somewhere in your path (e.g. /usr/local/bin) or alternativly add the bin/ directory to your PATH environment. Last, set your CLASSPATH environment variable (e.g. in /etc/profile) to <LIST> <ITEM>/path/to/java/lib/classes.zip with JDK 1.1.x <ITEM>/path/to/java/jre/lib/rt.jar with JDK >= 1.2 </LIST> You should have a running system now. Test it by typing "java -version". Special note for Linux users: There are problems with earlier versions of the libc6 (aka glibc). Please use glibc 2.1.2 or above to ensure a stable environment for WebMail. </SUBSECTION> <SUBSECTION name="Improving speed" id="java:speed"> To improve Java performance, you will most likely use an JIT (Just in time compiler) that compiles bytecode to native code on-the-fly (while executing the program). This especially improves speed for routines that are used frequently, as it is with WebMail. So I strongly recommend using a JIT for WebMail! If you already have Java 1.2 (aka Java 2) or the IBM JDK 1.1.8 on Linux, you won't need to get a JIT as it already ships with one. If you still have Java 1.1, it depends on your platform. <LIST> <ITEM>On Linux (Blackdown port) you will need to fetch an extra JIT. I recommend using TYA, but you can get a list at http://www.blackdown.org</ITEM> <ITEM>On Solaris, a JIT is already included in the Java 1.1 releases </LIST> I don't know what it's like for other platforms. You can always try whether you have a JIT or not by setting JAVA_COMPILER to "NONE" and testing whether that affects the execution speed of WebMail. If it is considerably slower, than you most likely already have a JIT.  The Sun JDK 1.3 (all platforms) includes a new techology called "HotSpot". This can also dramatically improve performance for WebMail. For WebMail to make full use of HotSpot, you should comment out the "HOTSPOT=-server" option in webmail.sh or if you are using the servlet version start JServ with the -server parameter. This will produce a high load during the first seconds of startup, but will go down after some time when the HotSpot optimizations are in effect. </SUBSECTION> <SUBSECTION name="Glossary" id="java:glossary"> <TABLE> <TR> <TD>JDK </TR> <TR> <TD>JRE </TR> <TR> <TD>JVM </TR> <TR> <TD>JIT </TR> </TABLE> </SUBSECTION> </SECTION> <SECTION name="License" id="license"> WebMail is (c)1998-2000 by Sebastian Schaffert, schaffer@informatik.uni-muenchen.de WebMail is distributed under the terms of the GNU General Public License (GPL). You can find a copy in the file <A href="COPYING">COPYING. The LGPL allows you, said in short, to add WebMail to other projects that are not covered by the GPL. </SECTION> <SECTION name="Contributed Documentation" id="doc_contrib"> Contributed Documentation is documentation that has been provided by people that are not core WebMail developers but have managed to run WebMail on different platforms/systems and taken the effort to provide you with some sort of extra documentation (thanks a lot, BTW). I (Sebastian Schaffert) have not tested what you will find here. <SUBSECTION name="Installing WebMail on Resin" id="resin"> <NOTE> Resin is a framework for websites based on Apache that allows to run Java Servlets among other things. The following was contributed by Jesper Weissglas, jeppe@shapeshifter.nu. </NOTE> The deployment descriptors of Resin are sort of Servlet API 2.2 compatible, as opposed to the Apache properties files. Here is a skeleton of what will work with Resin 1.1: Assuming the webmail binary distribution is unpacked as <CODE>[homedir]/webmail <TABLE> <TR> <TD> <CODE> [homedir]/WEB-INF/web.xml </CODE> </TD> </TR> <TR> <TD> <CODE> <web-app> <classpath id='WEB-INF/classes' source='WEB-INF/classes'/> <classpath id='webmail/lib/webmail-servlet.jar'/> <classpath id='webmail/lib/webmail-common.jar'/> <classpath id='webmail/lib/authenticators'/> <classpath id='webmail/lib/plugins'/> <error-log id='log/error.log'/> <servlet-mapping url-pattern='/servlet/*' servlet-name='invoker'/> <session-config session-max='4096' session-timeout='120'/> <servlet servlet-name="webmail" servlet-class="net.wastl.webmail.servlet.WebMailServlet"> <init-param webmail.plugin.path="[homedir]/webmail/lib/plugins" /> <init-param webmail.auth.path="[homedir]/webmail/lib/authenticators" /> <init-param webmail.data.path="[homedir]/webmail/data" /> <init-param webmail.lib.path="[homedir]/webmail/lib" /> <init-param webmail.template.path="[homedir]/webmail/lib/templates" /> <init-param webmail.storage="net.wastl.webmail.storage.mysql.MySQLStorage" /> <init-param webmail.storage.sqlhost="localhost" /> <init-param webmail.storage.sqllogin="" /> <init-param webmail.storage.sqlpass="" /> <init-param webmail.storage.sqldb="[your_database_name]" /> </servlet> </web-app> </CODE> </TD> </TR> </TABLE> </SUBSECTION> </SECTION> <SECTION name="Credits" id="credits"> I give my credits to all who reported me bugs and made suggestions to improve WebMail. Some, however, I want to mention explicitly: <LIST> <ITEM>Devin Kowatch, devink@webengruven.org, for contributing challenge/response authentication <ITEM>Homero Borgo, homero@apoyo.uson.mx, for testing WebMail under rough conditions and helping much to find bugs in the product.</ITEM> <ITEM>My girlfriend for her patience and the cool icons for WebMail 0.5 and 0.6 <ITEM>The people at Bibop in Italy, especially Gianugo Rabellino and Ricardo Rocha for doing the Bibop Theme and lots of inspirations</ITEM> <ITEM>Sacha Berger, bergers@informatik.uni-muenchen.de, for some very interesting discussions about how to do things right.:-)</ITEM> <ITEM>Jesper Weissglas, jeppe@shapeshifter.nu, for the documentation about how to install WebMail on Resin</ITEM> </LIST> Sebastian Schaffert, schaffer@informatik.uni-muenchen.de </SECTION> </README>

What this is

This file is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

The source code

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

<!-- CVS ID: $Id: README.xml,v 1.1.1.1 2002/10/02 18:41:44 wastl Exp $ -->

<!--
 * Copyright (C) 2000 Sebastian Schaffert
 * 
 * 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.
-->

<!DOCTYPE README SYSTEM "README.dtd">

<README>
  <TITLE>WebMail v0.7.2
  <AUTHOR>Sebastian Schaffert, schaffer@informatik.uni-muenchen.de
  <SECTION name="Contents" id="contents">
  <SECTION name="What is WebMail" id="about">
    <P>
      WebMail is a server application that allows ISPs to provide a WWW interface 
      for each user to his mailbox(es) (similar to the programs YahooMail or HotMail 
      use). WebMail should scale well enough to support large userbases and 
      should be easy enough to be used in a home LAN.
    </P>
    
    <SUBSECTION name="Features" id="about:features">
      <P>
	Features include:
	<LIST>
	  <ITEM>Gives a user full access to his/her IMAP mailbox through a simple-to-use WWW interface
	  <ITEM>Supports multiple folders on multiple hosts, depending on mail protocol used 
	    (IMAP supports different folders on the same host, POP doesn't)</ITEM>
	  <ITEM>Sophisticated folder management system
	  <ITEM>100% HTML 3.2/4.0 output, no Javascript, no Java on the Client side
	  <ITEM>supports multiple languages, configurable for each user
	  <ITEM>flexible template system to personalize look and feel and write new language files using XML and 
	    XSL</ITEM>
	  <ITEM>runs as Java Servlet in Apache or as a standalone HTTP-server completely written in Java
	  <ITEM>Improved session management keeps mail connections alive
	  <ITEM>Improved speed compared to CGI scripts (about factor 5-10, depending on usage)
	  <ITEM>Usage of JavaMail-API ensures compatibility to many mailstandards 
	    ("officially" supported and tested: IMAPv4)</ITEM>
	  <ITEM>Open Source distribution allows easy customization
	  <ITEM>webbased administration interface
	  <ITEM>support for multiple virtual user domains
	  <ITEM>Easily add new features through the WebMail modular plugin concept 
	    (support for dependencies, hooking into URLs, etc)</ITEM>
	</LIST>
      </P>
    </SUBSECTION>

    <SUBSECTION name="Whom WebMail is aimed at" id="about:audience">
      <P>
	Who should use WebMail:<BR/>
	WebMail's primary goal is to provide ISPs, companies and universities with a 
	simple and zero-cost solution to give WWW mailaccess to their users.<BR/>
	Users can read and write their email while they are sitting in an Internet-Cafe,
	at expositions, etc without having to carry their PC around.<BR/>
	It is not intended as a replacement for the different personal email clients, 
	but as a supplement for an existing mail solution.<BR/>
	The secondary goal is to unify a user's different email accounts under one 
	interface which is easily accomplished using WebMails folder capability.
      </P>
    </SUBSECTION>
  </SECTION>

  <SECTION name="Installation" id="install">
    <SUBSECTION name="Introduction" id="install:introduction">
      <P>
        There are two different ways to install WebMail, the <EM>standalone installation and the
        <EM>Java Servlet installation. Which one you should choose depends on what you plan to do
	with WebMail:
        <LIST>
          <ITEM>
	    a <STRONG>standalone server is much easier to install and will allow you to run
	    WebMail almost immediately without much configuration. This can be used if you want to
            evaluate WebMail's capabilities or develop new features/bugfixes. It also makes sense to
            use this for small to medium installations if you don't want to set up a Java Servlet
            capable webserver
          </ITEM>
          <ITEM>
            a <STRONG>Java Servlet installation is recommended for production use since it 
	    allows greater performance and scalability. You will need to set up a webserver that is
            capable of serving Java Servlets, e.g. Apache. I can't give too detailed instructions here
            since this depends in large parts on your webserver, but I include a sample Apache 
            configuration (the parts relevant to WebMail) in the distribution.<BR/>
	    The Debian (unstable) and RedHat (6.2) packages will install WebMail as a servlet for these
	    two systems. This will ease the servlet installation a lot since you need not set up JServ and
	    WebMail manually, so you should consider using this approach if you have one of those systems.
          </ITEM>
        </LIST>
      </P>
<!--      
    </SUBSECTION>

    <SUBSECTION name="Standalone Server" id="install:standalone">
      <NOTE>On RedHat and Debian Linux systems you will probably first want to have a look at the
	RedHat and Debian sections in the Servlet installation instructions</NOTE>

      <SUBSUBSECTION name="Requirements" id="install:standalone:requirements">
        <P>
	  To run WebMail properly on your server, you need to have the following software 
	  installed:
          <LIST>
	    <ITEM>Java 1.1.6 or better - seethe Java Section on Java issues
            <ITEM>
              About 20 megs of RAM (minimum) plus additional 80 megs on high load servers
              (these are just recommendations, WebMail will run on any Java-capable server;
              if you have less than 32 MB RAM, you should try to adjust the settings in
              the startup script called webmail.sh/webmail.bat)
            </ITEM>
            <ITEM>
	      Using a JIT ("just in time compiler") is greatly recommended! The Solaris and Windows 
	      JDKs from Sun use a JIT by default (sunwjit). On Linux, the Sun/Blackdown JDK uses a JIT,
	      however it is not very fast, so you could profit from using a JIT like tya. The IBM Linux 
              JDK 1.1.8 comes with a very fast JIT (actually the fastest Java platform available).
            </ITEM>
          </LIST>
        </P>
        <P>
          WebMail has been successfully tested on:
          <LIST>
            <ITEM>Solaris x86 and SPARC, JDK 1.1.6 and JDK 1.2
            <ITEM>Linux x86 (tested: Debian and SuSE), IBM JDK 1.1.8 and Sun/Inprise JDK 1.2.2 (RC3)
            <ITEM>FreeBSD 3.4 x86, JDK 1.1.8
            <ITEM>Windows NT/2000 (did not do the tests myself)
          </LIST>
        </P>
        <P>
	  WebMail will make profit of multiprocessor machines (e.g. Sun Enterprise 450) as
	  it is multithreaded in large parts.<BR/>
        </P>
      </SUBSUBSECTION>

      <SUBSUBSECTION name="Binary Installation" id="install:standalone:binary">
        <P>
          <NLIST>
	    <ITEM>Change to the prefix where you want to install WebMail (e.g. /usr/local)
            <ITEM>Unpack the tar.gz or zip archive: tar xzvf webmail-0.7.0.tar.gz
            <ITEM>Change to webmail/bin
	    <ITEM>Edit the file webmail.sh if necessary
            <ITEM>Start WebMail using the provided script 
	      <CODE>./webmail.sh >> stdout.log 2>&1 &
            <ITEM>See Configuration for further steps to take.
          </NLIST>
        </P>
      </SUBSUBSECTION>

      <SUBSUBSECTION name="Source Installation" id="install:standalone:source">
        <P>
          <NOTE>Source installation will definately only work on Unix systems!
          <NOTE>Source installation is only really useful for developers since you don't need to
	    (and cannot) adapt the program to your specific system settings in Java and I already
	    compile with optimization turned on.</NOTE>
	</P>
        <P>
	  Additional requirements:
          <LIST>
	    <ITEM>GNU make (Only GNU make will work)
            <ITEM>zip/unzip
          </LIST>
        </P>
        <P>
          To install the source distribution of WebMail you will have to take the following steps:
          <NLIST>
            <ITEM>Change to the src/ subdirectory
            <ITEM>Set the CLASSPATH environment variable to your classes.zip (JDK 1.1) or
	      rt.jar (JDK 1.2) archives (on Solaris: /usr/java1.1/lib/classes.zip for
	      JDK 1.1 and /usr/java1.2/jre/lib/rt.jar for JDK 1.2)
            </ITEM>
            <ITEM>Have a look at the makefile and edit it if necessary
            <ITEM>
              Call "make" to compile the classfiles and create the archives
	      (containing classfiles, language dependent HTML templates and images).<BR/>            
	      You will find the compiled archives in the lib/ directory when the 
              compilation was successful. 
            </ITEM>
            <ITEM>See steps 3 to 5 from binary installation then
          </NLIST>
        </P>
      </SUBSUBSECTION>
    </SUBSECTION>

    <SUBSECTION name="Servlet Installation" id="install:servlet">
      <P>
	Running WebMail as a Servlet has several advantages over the standalone installation (and
	also some disadvantages):
	<LIST>
	  <ITEM>you can run (and integrate) WebMail on an already-running webserver
	  <ITEM>
	    you can make use of the webserver's fast connection handling and HTTP parsing routines
	  </ITEM>
	  <ITEM>
	    you can e.g. use Apache's load-balancing feature to run WebMail on a whole server cluster
	    for large installation.
	  </ITEM>
	  <ITEM>
	    installation is however much more complicated (and so it is definately not suited for 
	    webserver newbies)
	  </ITEM>
	</LIST>
      </P>
      <P>
	Before trying this, please ensure that you are familiar with your Webserver's
	Servlet configuration. I provided a sample zone file for Apache, though (but
	you will have to do many modifications concerning the initArgs at the end of
	the file).
      </P>

      <SUBSUBSECTION name="General information" id="install:servlet:general">
	<P>
	  The WebMail servlet is called <CODE>net.wastl.webmail.servlet.WebMailServlet. This
	  class is contained in the <CODE>webmail-servlet.jar Java archive. Usually you will
	  need all of the provided JAR files except <CODE>webmail-standalone.jar to run the
	  WebMail Servlet.
	</P>
	<P>
	  The WebMail servlet uses the following <CODE>initArgs:
	  <TABLE>
	    <TR>
	      <TD>webmail.plugin.path

Path were data will be stored (this has to be writeable by the process owner of the webserver)</TD> </TR> <TR> <TD>webmail.lib.path

http://java.sun.com

http://www.ibm.com (IBM JDK 1.1.8 / IBM JDK 1.3)

http://www.blackdown.org (Blackdown port of JDK 1.2)

http://java.sun.com (Sun and Inprise port of JDK 1.2 / JDK 1.3)

http://business.tyler.wm.edu/mklinux/

http://www.voicenet.com/~gatgul/JDK/java-alpha.html

http://tinukai.sesuadra.org/~jdk/

http://www.ibm.com

http://applejava.apple.com

http://www.ibm.com

http://www.freebsd.org/ports/lang.html

Java Depelopment Kit - what you need to compile programs

Java Runtime Environment - what you need to only run programs

Java Virtual Machine - bytecode interpreter

Just In Time Compiler - improves execution speed of the JVM

Copyright 1998-2024 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.

What this is

Other links

The source code

new blog posts

... this post is sponsored by my books ...
#1 New Release!	FP Best Seller