|
|
JWebMail is a web mail server. Web mail allows an organization to provide a WWW interface for each user to his mailbox(es). Unlike Yahoo Mail, Hotmail, and Gmail, JWebMail presents a web interface to traditional email accounts which you or somebody else provide. The target email account servers may be restricted by JWebMail.
By virtue of JWebMail being a pure Java appplication, it has excellent portability, scalability, and performance. We have designed JWebMail so that it works out-of-the-box for a home LAN setup by just dropping the .war file into your servlet container (which includes all modern application servers).
Common use-cases
Features include:
imaps and pop3s.
|
For running JWebMail you need the following software:
localhost for both
mailapi-*.jar)
You can download
version 1.4.1 of the JavaMail API library here.
smtp-*.jar).
You can download
version 1.4.1 of the SMTP library here.
If you wish to build a custom app, or develop, you will also need a standalone Java JDK 1.5 or later, and Ant 1.7 or later, as described below. Any or no Java IDE will work.
Top of section "Requirements"There are separate sections below, depending on whether you want to just run JWebMail, or to build it on the command-line or with an IDE.
This is the preferred installation method if you just want to run JWebMail, and have no need to customize the application iteself.
This installation is very simple:
Install jwebmail.war as you would install any War file.
With Tomcat, the easiest way is to use the Manager webapp, which serves http://localhost:8080/manager/html by default. Log in and deploy the war using the Gui (you can see or add manager accounts in the file $CATALINA_BASE/config/tomcat-users.xml).
For every application server that I know of, if you have auto-deploy on (usually the default mode) you can become the app-server owner (the account under which the server process(es) run), and just copy the war file into the webapp landing directory. If you don't have access to that account, see your app server docs, because the war file permission requirements vary (if you have superuser privileges, you can always change the file to be owned by the app-server owner). Rest assured, your app server has several easy ways to deploy war files.
JWebMail is then available by visiting http://yourhost:PORT/jwebmail with a web browser.
Please don't forget to visit the administration interface first. You can access
it by browsing http://yourhost:PORT/jwebmail/admin. Initial password
is Secret.
JWebMail is compiled by using the Ant build-system. You will need Ant version 1.7 or greater and Java JDK 1.5 or greater to build JWebMail.
You can obtain the JWebMail source code by extracing a source code
distribution package, or by exporting or checking out our code from
SourceForge. You can get our distro packages at
https://sourceforge.net/project/showfiles.php?group_id=2056.
You can use any Subversion client to get our trunk code from
https://jwebmail.svn.sourceforge.net/svnroot/jwebmail/trunk.
The following steps are required (for a quick-start):
bin directory of your Ant installation is in your
search path. Run "ant -v" to verify.
dist.
If you don't have an
Ivy
jar file in your CLASSPATH, the Ant command
above will display the simple command that you can copy-and-paste to your
command line to satisfy it.
Note:
An error message like
...doesn't support the nested "matches" element...
means you need to upgrade Ant to 1.7 or later. |
dist/jwebmail.jar to your servlet container, as
explained in the previous section.
Alternatively, you set Ant property exploded.dir
and deploy the exploded webapp to a live deployment directory.
Since you are building software, we figure you
are handy enough to figure this out without further instruction from us.
Run "ant -p" for further possible targets that may be used.
To customize any Ant properties, create a standard Java properties file in
this directory with name local.properties.
Most developers will want to use the targets
gen-guide and javadoc to build documentation.
(They get written to the build/apidocs and
doc subdirectories respectively).
Unless the version of the User's Guide you are reading is out-of-date,
you probably won't need this, but...
The gen-guide task requires the program "xsltproc".
You have a few alternatives to access a User's Guide if you don't
have xsltproc.
The build system uses Apache Ivy to fetch third party libraries. The configuration allows you to change the library repository location by editing local.properties and ivy-settings.xml. See http://ant.apache.org/ivy/ for details about Apache Ivy.
Code contributors must read and follow the coding conventions listed
in the conventions.txt file located in the doc
subdirectory.
It's important to not submit files which should not be
change-controlled, and to set the right Subversion file properties.
The easiest way to accomplish this is to put
the supplied file samples/config-svn.txt into
place at $HOME/.subversion/config on UNIX-like OSes,
or wherever your Subversion client wants it on Windows.
When you submit code, always add a meaningful subversion commit
message which very briefly describes what you have changed, added,
or removed.
At this point in time, we only have the JWebMail pre-configured for Eclipse. Any developer who has a strong preference for a different IDE should be capable of getting things working in it. If you do this in a way to share the configuration in a fool-proof manner, like we do for Eclipse, please contact me to get these improvements into the code baseline.
Here are the steps to start from 0 and get JWebMail building. Most developers will skip many of these steps because they probably already have some of the components in place.
-initialize switch.
Help / Software Updates and click
the Install button.
Bring up a web browser at the same time and browse to
http://www.polarion.com/products/svn/subversive.php?src=eclipseproject.
Back in Eclipse, click the Available Software tab
and Add the two "required" URLs listed in the "Latest Release"
section of that web page.
Select the latest available release of each of the four following
items and install them.File / Import
and import from Subversion.
Enter URL of https://jwebmail.svn.sourceforge.net/svnroot/jwebmail/trunk
and no other detals (unless you're a team developer).
If it craps out, restart Eclipse and retry... or it could be a
bad Internet connection to Sourceforge.
Window / Show View / Ant.
Click the target icon in the Ant view toolbar to hide internal
Ant targets.
Right click in the view and add the Ant build file
build.xml from the root directory of the project.
At this point all of the listed Ant targets should work,
except for gen-guide and all, if you
don't have xsltproc installed.
Double click on jwebmail to execute the default target,
which builds the war file.
You will probably also want to execute the target
javadoc to build the JWebMail API spec docs with
entry point of build/apidocs/index.html.
Preferences / General / Workspace to turn
Build automatically off and Refresh
and Save on.
Project / Clean... to clean just
the jwebmail project...
and turn off the nasty Start a build immediately
button (definitely a bad thing for shared Ant setups).
eclipse-setup and set the
build variable as you instructed in the console output.
People contributing code to the JWebMail project must create code that isn't difficult for other developers to work with, and must commit resources in a way that doesn't clobber other workers. Even if you aren't going to commit code to our project, you're welcome to use these procedures if you just like developing like a professional, or if you are sharing with somebody else.
Build and Install from source section bove.
Apply
and OK when changing Eclipse preferences.
It's much better now than with older versions, but Eclipse is known
to sometimes not get your changes.
If that happens, just repeat and make sure you apply.
Back to the task at hand, go to
Windows / Preferences / Team / SVN / Properties Configuration
and Import the file samples/config-svn.txt.
This file has specifically been massaged to do what it needs to do
while accommodating several serious parsing bugs in the Eclipse
Subversive plugin.
Window / Preferences / Java / Code Style
First, go to the Clean Up and Import the file
samples/cleanup-ecpro.xml.
Formatter and Import the file
samples/formatter-ecpro.xml.
Note that this formatter disabled word-wrapping for Java files,
because Eclipse does a truly terrible job at it.
It doesn't even enforce the rules as it explains and exemplifies them.
Sorry to say, but after running Eclipse's code formatter, you'll
need to apply word-wrapping manually (according to
doc/conventions.txt.
(The formatter works perfectly well for Javadoc and non-Javadoc
comments).
Code Templates, but this time don't
load the profile at the global level.
That's because, whereas the other settings are good for any
Java project, these templates may not be appropriate for other
Java projects that you may work on in the same Eclipse workspace.
The only known issues with the code templates is that they will
insert useless blank Javadoc lines like " *" if there are no
tags for a method, and it will insert a blank line after {'s and
before }'s.
Configure Project Specific Settings....
Select the jwebmail project and click OK.
Click the Enable project specific settings checkbox.
Import the file samples/codetemplates-ecpro.xml.
Comments / Types and hit
the Edit... button.
(IMO it's rather counterintuitive that the lower box there is not
an editable box-- you must hit the Edit... button to
edit.
Change the text "Your Name Here" to your name, spelled out and
capitalized like that.
Properties for jwebmail... screen,
make sure to check the Automatically add comments...
button and click the Apply and OK buttons.
Webapp logging is best administered at the container level. Most servlet containers were designed to work this way, and many technology companies expend much effort to defeat Classloader design and manage logging with delivered application artifacts. Remember that logging settings are a runtime consideration which should be modifiable after deployment by operations personnel. JWebMail is exceptional in that it facilitates logging
Webapp bundles just Apache Commons Logging. Commons Logging provides the front end for logging, where the JWebMail application sends log messages. Your servlet container will connect these generated messages to a logging back end to write log files, database records, or emails from them. If you have a straight-forward servlet container, and you have not added a logging product to it, then Commons Logging will also handle the back end in the container space, just logging to the console or stdout/stderr log with default settings. But it is very easy to improve on that. Some application servers have logging management utilities, and you can use them to pipe the JWebMail log entries to destinations using Gui tools or text files. You'll have to see your App Server documentation about these tools. Otherwise, you can put text files in container-level classloader directories to easily set up text, HTML, and even email-alert logging.
I will explain how to set up really nice JWebMail logs using Log4J as the back end (container-side) logging product on Tomcat. In my experience, everybody is satisfied with Log4j. The procedure is very much the same to use another logging back end product (see the Commons Logging documentation about how to do it). The setup procedure is the same for other servlet containers (that don't force their logging management system on you), except you just need to find out where the system classpath directories are (or how to add them).
Container logging setup with Log4j and Tomcat
CATALINA_HOME/lib by default.
I.e., the "lib" subdirectory
of the Tomcat installation root directory.
You can put both Jar files and in .class files (in package
directory trees) into it.
(You can add other classpath directories by changing the
setting common.loader in the file
conf/catalina.properties).
log4j.xml from the samples directory
of your JWebMail distribution into the servlet container classpath directory.
logdir.common for Tomcat.
Our log4j.xml file uses this variable to set the
destination directory for log files independently of where Tomcat
is started from. The best way to set Java System Properties for
Tomcat is by setting the environmental variable CATALINA_OPTS.
Where to set this variable depends on how you start Tomcat.
If you use one of Tomcat's startup scripts directly on the
command-line, then set the variable according to these samples.
On Windows,
CATALINA_OPTS="-Djava.awt.headless=true -Xms512m -Xmx1024m -XX:MaxPermSize=256m -Dlogdir.common=$HOME/logs"
set CATALINA_OPTS=-Djava.awt.headless=true -Xms512m -Xmx1024m -XX:MaxPermSize=256m -Dlogdir.common=c:/logs
log4j.properties file instead.
See the Log4j documentation about how to set up email alerts
with the SMTP appender, how to log to a database, etc.
Be aware that the file (log4j.xml or
log4j.properties) will control all messages which
reach Log4j in the container space.
If you have three other web apps deployed to this container without
log4j jar files bundled, their log messages will also be filtered
by this file.
Regardless of the container and logging product, if you manage logging at the container level without a Gui, the server classpath file will be the central point of application log management for the container. You can use package names to route messages to application-specific destinations (files, emails, etc.). The only tricky part of container-managed logs is routing messages initiated by classes common to more than one webapp. This isn't the place to discuss how to route such messages, but you generally don't have to worry about it if your app catches all throwables, and you have the same app deployed more than once-at-a-time.
Top of section "Logging setup"
|
JWebMail has an administration interface which allows you to perform several runtime administration tasks, including:
By default, when you install the web application, a XML storage are will be set up under the servlet container owner's home directory. The location, and many other things can be changed, but data should not be written under the context root (appication deployment directory).
| Note: A database storage option (JDBC) is planned, but implementation has not yet begun. |
You can connect to the administration interface with your browser by simply entering
the URL http(s)://webmail_server:port/jwebmail/admin in the address field of your browser.
(set http/https and replace webmail_server and port with the correct values).
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.
Top of section "Connecting"The first page gives you a list of JWebMail 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):
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). |
Virtual Domains in JWebMail are a quite new concept (thanks to Oswaldo E. Aguirre M. for the idea).
They basically provide the following features:
user@domain"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 JWebMail 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)).
Top of section "JWebMail Virtual Domain Support"You can add, edit and delete users from the administration interface (Note that you don't have to create users before they may use JWebMail since they get default settings when they first log on authenticating against IMAP, POP or Unix).
To create a user,
user@domain")To edit a user,
To delete a user,
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.
Top of section "Viewing JWebMail Status"Top of section "JWebMail Administrator Plugin"
|
JWebMail supports extended user authentication. At the moment, the following authentication methods are supported:
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.
|
The JWebMail daemon listens on whatever port you have configure. Just point your browser´s URL to http://yourhost:yourport/jwebmail 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. JWebMail 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.
JWebMail should also work with Proxy Servers and other Clients than Netscape Communicator.
Top of section "General Usage"JWebMail supports as many IMAP folders on as many different hosts you like.
JWebMail 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).
Top of section "Folders"
|
JWebMail supports the usage of different languages on a per user basis.
Since v0.6.0 JWebMail 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 JWebMail to a new language, please read the file "Translating"
in the developers' documentation (source only).
|
JWebMail Pre-1.0.1 is BETA.
Some features on the wish-list are
See the file changes.txt for a list of changes in the different
JWebMail releases.
|
JWebMail is copyright 2008 by the JWebMail Development Team and Sebastian Schaffert.
The base JWebMail product is distributed under the terms of the Apache 2.0 license. You can find a copy in the file LICENSE.txt, or at http://www.apache.org/licenses/LICENSE-2.0.
The Bibop theme is copyrighted under the supplied GPL 2 license.
Top of section "License"
|
Contributed Documentation is documentation that has been provided by people that are not core JWebMail developers but have managed to run JWebMail 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.
Top of section "Contributed Documentation"
|
Appreciation to all who reported bugs and made suggestions to improve JWebMail.
Some, however, I want to mention explicitly:
Blaine Simpson, [email protected]
Top of section "Credits"