If upgrading from a version of JWMA before 4.5, and if serialized storage of user settings and contacts was used, sorry, but all existing files in the JWMA home data directory must be deleted. There's no option to retain contact lists other than to copy them off while the older version is running and re enter them. Derby storage is unaffected.

The server administrator configures basic options by editing a simple config file which jWMA generates on first run; it should allow you to make a start though without any changes. Here are set protocol (imap or imaps), ports, mailbox format (mbox or maildir) and the default language that's offered to users. Individual users can separately choose the language of the interface and select from a few other options. By default these user settings are persisted as serialized objects, but the administrator's config file also has options for database storage (postgresql, mysql or embedded derby). It's a very long time since the first two of those were tested, but derby support is built in, solid and fully documented in the source download zip archive.

Installation

This assumes a machine running a suitable imap server, mail exchanger and java webapp container. As noted above, all this is documented elsewhere.

You can download JWMA as a ready to go binary and source code (still supplied in a zip archive in case a windows user wants to try it) from sourceforge, Build files to compile the source code make this a quick (few seconds) and simple process. Simply move a build script from the build_scripts directory up to the base webmail directory. There are three for use either with ant, the linux shell or windows powershell (this has not been tested).

The webmail.war binary (either downloaded or compiled from source) is moved to the appropriate place for your webapp server (note additional step recommended for jetty) and it will start up and load the login page. If you have a system user account on the imap server and it's offering an imap service on port 143, you should be able to login and access your email. I know of one unusual situation where this will not work - see my dovecot writeup for details (the note on fscrypt).

This version of JWMA queries a dovecot install to determine mbox or maildir storage and defaults to maildir if that fails. This can be altered by restarting JWMA after editing the config file if necessary. From this point on you can jump to the user guide section before coming back to look at a few additional tweaks.

Configuring

On first run under either tomcat or jetty, JWMA creates a jwma home directory and a confid file.

############
#jwma.config
############

#access_protocol - the mailbox access, either imap or imaps
access_protocol = imap

#access port, probably either 143 for imap or 993 for imaps
port = 143

#available interface languages
languages = de,en,es,fr,it

#the login screen language and the default choice for users
language = en

#users config & contacts persistence - one of serialize, postgres, mysql or derby
persistence = serialize

#1 - session is kept alive or 0 - it times out after 30mins unless compose message page is open
keep_alive = 1

#log level one of ALL < DEBUG < INFO < WARN < ERROR < FATAL < OFF
log_level = DEBUG

#mailbox format, either mbox or maildir
mailbox_format = maildir	

If you make changes to the config file, you need to reload the webmail app or restart tomcat/jetty, to have the changes picked up.

• access_protocol - this can be changed to from imap to imaps, if you do this you will need to insert a certificate into the jvm's store; see Security.
• access port - this will probably need to be changed from 143 to 993 if you switch to imaps.
• languages - currently there are five European languages available. You could add to these (see Internationalization) or even remove from the comma separated list if you don't want to support them.
• language - the default language, one of those that appears in languages. This will be used at the login screen, but individual users are able to select a different languages once they are logged in.
• persistence - this must be set to serialize (the default), postgres, mysql or derby.
• keep_alive - if this is set to 1 the session never times out, changing this to 0 allows time out after 30 mins of inactivity on the server, except when the compose message window is open.
• log_level - default setting is DEBUG, you can reduce log verbosity by changing this to a lower setting. This only works where the web server explodes the war file (as does tomcat) and settings below WARN are not recommended.
• mailbox_format - defaults to maildir the underlying system used by imapa server and mail exchanger cannot be determined. mbox is the alterantive. maildir is the correct setting if you're running james with it's embedded derby database. All systems (imap server, smtp server and jwma) must use the same mailbox format.

No per user configuration is necessary other than there must be an pre-existing imap account. JWMA passes login details through to the imap server, dovecot, and a jwma account is automatically created for each user the first time they log in. With the default persistence setting, preferences and contacts for each user are stored in two separate files, inside the .jwma/data directory. Before switching to database persistence see the next section.

Data storage

This is an alternative to the default serialization of individual users preference choices and contact lists. I'm only going to deal with the derby option here as I've not tested either postgresql or mysql recently. The source archive retains the notes on using these two databases with JWMA as well as information on seting up a derby database from scratch using it's ij tool.

derby

A suitable embedded derby jar (containing the jbdc driver) is supplied in the zip archive. Refer to tomcat / jetty instruction for where to put this and necessary config changes.

On the JWMA side, unzip the prepared jwmaDB file from the database directory in the source archive, ensure ownership of its files are the same as the user that runs tomcat and move it to .jwma/derby/jwmaDB. With persistence = derby configured in .jwma/jwma.config. Remember that JWMA, or the web app container must be restarted for changes to take effect. You will of course have to re-enter any user configuration changes you made and contacts that you already stored.

Internationalization

JWMA is a genuinely internationalized app; the system administrator can configure the default language, but please note that supplied translations from English are almost certainly flawed - see to do. All users can make their own selection which is recorded in their preference settings, see User Configuration. They do this entirely independently of other users and the default language, although this is always presented at the login screen.

To add another language copy a StripesResources properties file in /webmail/web/WEB-INF/classes to StripesResources_xx.properties (where xx is something suitably representative), translating the right hand side of = on each line of the file. Add the appropriate xx to the languages list in jwma.config and reload or restart the app server.

Security

Authentication is managed by the imap server with JWMA merely passing details through to it. Since it's running on the same machine as the imap server, I don't believe that passing these in plain text is an issue. Nevertheless, there are features built into jwma that have security in mind and also configuration changes that can be made with the same objective.

The user name, but not the password, is stored in the session object. Databases are protected from malicious input, by checking and sanitizing user input for storage.

Logs

JWMA writes and rotates logs files which will include evidence of any nefarious activity; all login attempts are recorded, together with the source ip address if authentication fails. Log files are stored in the .jwma (or jwma on Windows) directory.

As with any web-based service on a public network, it is good practise to monitor these logs; I suggest logwitch for help with this. If you're responsible for a system with a lot of users, it's worth looking out for WARN and ERROR entries such as these:-

ERROR JwmaExceptionHandler - net.sourceforge.stripes.exception.ActionBeanNotFoundException: 
Could not locate an ActionBean that is bound to the URL [/Admin.jwma].

2016-08-05 18:09:07,215 WARN  JwmaAuthenticator - login FAILED for david
2016-08-05 18:09:07,216 WARN  LoginAction - FAILED login from 94.2.235.163

A single pair of entries similar to the second example may simply be due to a typo, but if you see something similar to the first example I'd recommend having a word with the user in question (there is no Admin.jwma page).

You may wish to make use of the ability to set logging levels in the config file; once you are satisfied that jwma is running smoothly, you could reduce log verbosity. I'd suggest not going any lower than the WARN setting.

https and imaps

Presenting the login screen over https avoids the risk of passwords being sniffed. There are a number of ways to set this up, some being dealt with in the tomcat and jetty writeups.

Moving from imap access to imaps is another config change that should be considered from the standpoint of security. The java environment must have knowledge of a certificate supplied by the server, this being described in the java writeup and also specifics for dovecot. Unlike Debian/Devuan, the Fedora distro is imaps ready on install, with the dovecot certificate at /etc/pki/dovecot/certs/dovecot.pem. From the JWMA side:-

#access_protocol - the mailbox access, either imap or imaps
access_protocol = imaps

#access port, probably either 143 for imap or 993 for imaps
port = 993

the Session

The default web.xml file specifies a session length of 30 minutes, but with the standard keep_alive = 1 in jwma.config this is overriden by javascript pokes from client browser to server. A session is created when a user logs in and we rely on a logout for it to be closed.

This situation is probably fine where there are only a few, educated users and it is also a nice feature to have the INBOX update automatically and indeed pretty essential that the session does not time out while a user is writing a lengthy email. If this is unlikely to scale too well on your install, you can change the setting to keep_alive = 0. The session is still kept open if the user is composing a message (despite typing on the client not registering on the server!), but if other screens are left inactive the session will be closed after 30 minutes.

Miscellaneous

file system access

If users find that operations such as deleting messages and creating mailboxes fail silently, without a warning in red coloured text, this is probably due to insufficiently permissive access controls to parts of the system involved in mail handling.

It's important to remember that with a system using mbox mail storage, the users INBOX may actually be a file under /var/mail or /var/spool/mail rather than being located in the home directory. On a recent Debian install deleting messages from the INBOX fails:-

root@raylor # ls -l /var/
/\/\/\/\/\
drwxrwsr-x  2 root mail  4096 Oct  6 06:25 mail
\/\/\/\/\/

Changing permissions fixes this:-

root@raylor # chmod o+w /var/mail/

root@raylor # ls -l /var/
/\/\/\/\/\
drwxrwsrwx  2 root mail  4096 Oct  6 06:25 mail
\/\/\/\/\/

Similar problems with message and folder manipulation outside of the inbox will probably be fixed by attending to permission in the mail or Maildir directory in the user's home directory. Additionally SELinux issues may be encountered, particularly with an mbox system. If you use this (it runs by default on fedora). I suggest initially turning it off with echo 0 > /sys/fs/selinux/enforce, checking everything works and then fixing any issues that arise after turning it back on

Dovecot and exim4 setups are dealt with here.

Log in

On a desktop machine if you browse to the address given you by the administrator, you'll get the login screen where you can authenticate with your system username and password to access your email.



If you tick the Remember box a cookie is written to your browser. Depending on the browser's configuration, the Username field may be pre-filled next time you access the page. The link on the top left is there in case you arrived here using a small screen device; it will take you to the mobile interface, although hopefully that should have happened automatically. JWMA makes the assumption that you will mainly use a large screen device to manage your email with the mobile interface there to access the main features whilst you are away from home or office.

Main Page

This is where you land after a successful login and where you can quickly return to from the left most link on the navigation bar. What you see, to some extent depends on the underlying system used for email storage. First, here's JWMA running on a mbox system:-



From top working down, you see that the INBOX has 3 messages, one of which has not been read. The already mentioned navigation bar takes you to the other parts of the app as well as returning you here. Below that, on the black bar next to the small folder image there is a forward slash (/) character. This is the folder separator for the particular system that your email is stored on. It's helpful to know this if you want to create nested mailboxes ie mailboxes hidden from the main view.

Next the pre-exisiting folders and mailboxes are displayed. Folders, which can contain mailboxes are shown on the left and mailboxes which contain individual messages on the right. Although they can't be seen, it's likely that the archive folder contains some nested mailboxes. These would be revealed by clicking the folder name and the layout would remain similar to the one shown, but just listing mailboxes inside the folder rather than those logically directly inside the INBOX. If instead of clicking a folder, you click a mailbox, which includes the INBOX you are taken to a Message list for the particular mailbox.

Below here are options to delete selected folders or mailboxes, move mailboxes from their logical position inside the INBOX to another folder and create new folders or mailboxes. Finally the icon at bottom right shows that the Trash folder is not empty. In this state the icon is a link that takes you to a list of deleted messages.

Be aware that deleting a mailboxes moves all its messages to Trash and if you delete a folder all mailboxes nested in it will also be removed. As with deleting an individual message (see Message lists), the Trash mailbox represents a second chance, but if you delete messages from this mailbox, they really are gone. The same applies when you logout, unless you deselect Automatically empty Trash in the Settings menu.

If instead the administrator has set up a maildir system, what you see will look more like this:-



There is no Folder as opposed to Mailbox distinction as all folders can contain both messages and other folders nested within them. In both systems, jwma limits nesting to 2 levels, ie messages are logically stored directly in the INBOX or either one or two levels beneath it. Note that on this system the folder separator is a period/dot/fullstop (.) and that when the screen shot was taken although the INBOX and Trash were empty, the sent folder contains a single message.

Clicking the nested Folders link reveals the whole mail storage layout, not just the Mailboxes nested within a single folder as in the mbox system.



Finally, since this type of system does not distinguish mailboxes from folders, the Create new button does not need to offer that choice. It is only in this first main window that there is any visual difference apparent to the jWMA user between the two systems it supports.

User Configuration

Select Settings in the navigation bar and you'll be taken to this screen, which initially displays the default settings for each user.

You'll want to replace the Mail identity with one or more of your own email addresses. Note that you cannot delete the default until at least one alternative is in place. This is because it's not possible to send email without this setting.

If you select a different language all the screens (except the login page) will be translated accordingly. Note that by default Trash messages are automatically deleted when you logout; if you stick with this, although deleting messages from other mailboxes actually moves them to Trash, on logging out, they really will be gone.

By default, sent mail is not archived to an Outbox and there is no Draft folder for saving messages (even if there is a mailbox of that name); you'll probably want to select mailboxes for these roles, possibly creating them first back in the app's Main page.

Message display options:-

• 1. geek - plain text only display including the structure of the message
• 2. plain text - the default, a standard plain text display
• 3. block images - html messages displayed, but style sheets and images blocked
• 4. in line images only - as above, but with in line images displayed
• 5. allow all images - html messages as sender intended less any javascript.

You must press the Update button to make changes stick. Don't forget to do this after changing mail identities. As will be shown in the Reading messages section, there is a quick switch from display option 1 and 2 to view html messages as such for individual messages

Message lists

IMPORTANT! - any problem with deleting messages failing silently (no warning in red text) is probably due to this issue. The same applies to an attempt to create a mailbox or folder failing without warning.

Here's an mailbox with 3 messages; looking directly below the navigation bar you see this is the INBOX, but listings of all the mail boxes will appear the same.

You can Select all messages for a mass Delete or Move to; that can also be done on an individual basis by checking boxes on the left as appropriate. Delete is actually a move to Trash except for messages already there, when it really is a delete. Looking at the three individual messages, you see that two have been read (R) and the second has been answered (A). The third message has an attachment, which is indicated with *.

All are sent from different address, so there's no clarity to be gained in changing the sorted by setting to list messages by from address. The setting shown is not the default (rather Date oldest first), if this is changed the selection sticks automatically for all mailboxes and is remembered even if you logout.

Search allows you to create a list of messages from the current mailbox which contains your search term in the body of the message. Clicking on the subject of a message displays it (see Reading messages) and to the right, delivery date and message size are displayed.

Reading messages

The appearance of messages depends on the display style chosen in Settings.

This mail (not shown full length) is in the INBOX folder, that being a link which would take you back to its message list. As it's #3 in the folder of three messages it's the most recent, as chosen sort order has no bearing on this. To the right there are widgets for cycling through the messages in a folder and for presenting the message in a screen suitable for printing . Also a head and shoulders icon which will reveal and conceal the email headers. The current message display setting is option 1. geek so there is information about the structure of the message as well as its content.

This email (above) is displayed with option 2. plain text, so information about message structure is not included. Notice that there is a plain text/html toggle link, not present in the first message because this message has an html part. If we click that toggle, the display changes:-

This is equivalent to having selected 3. block images. Since this email has in line (rather than remote) images, we can click to either display or download them.

If we chose the former, this is the same display as would be had if we selected 4. in line images only. That the branding image apears between blocks of text may be correctly taken as an indication that JWMA now fully supports Content-id and the <img src="cid:xxxx" /> tag.

With that same setting (option 4), here's a different message that has remote images:-

You see a list of links to those images at the end of the display. Look at those filenames! My guess is these images have a tracking purpose and if accessed they confirm the email has been opened. In this screenshot, unlike earlier ones, the bottom of the browser window is visible with the buttons that allow you options to delete, reply to or forward the mail or move it to a different folder.

This message has rather more innocent looking remote images, shown here with setting 5. allow all images:-

The appearence of messages that you click on is not dependent on the folder containing them, with one exception. If you designate a draft folder in settings, its messages will be opened in a compose rather than display window; the assumption is that these messages have been part written and then saved rather than sent and so await further editing.

Sending Messages

As standard JWMA creates and sends messages as plain text.

The rich text link replaces the text area with an embedded html editor to allow the creation of html messages. There's discussion of this option, particularly regarding sending mail with inline, rather than attached images below. Incidentally, JWMA has now settled on a new html editor, it's an even more minimal version of the excellent jQuery extension Minimal Rich Text Editor.

If you use the Browse button to add a file attachment, two further file selectors will appear automatically, giving the option to attach up to three files. If an attachment is an image file many email clients (including jwma if Setting 4 or 5 are used for reading messages) will display the image as well as creating a download link for it.

Save Draft allows you to save a partially complete message into the folder you configured as described in the User configuration section. If you have not done this a warning is displayed. It is not functional if rich text was selected. A work around is to write and save a plain text message; when you reopen it from the draft folder you can copy the content before switching to rich text and paste into the code (</>) dropdown box.

No attempt is made to display forwarded messages before they are sent on; you see that the subject and recipient have been rewritten and a preamble stating that this is a forwarded message. You can edit this preamble before sending, but if you are forwarding a message with an html part, there's no guarantee the recipient will see this. Reason being that any preamble goes into a plain text part which may not be displayed.

Sending mail with images

You can of course send images without including any html markup by attaching an image file to a plain text message. If sent to a JWMA user, who reads mail with the option 4 style, an attached image file is displayed at the end of the message. So what follows is for a use case where you want an image to appear at a particular point of an email. There are three alternatives (four if you include the method mentioned in the developer sectioon. Some small knowledge of html markup is helpful.

It shoud be born in mind that the sender of an email cannot guarantee the configuration or capabilities of the recipient's email client. Your best effort to place and image in an email may not appear as you would hope when the recipient reads it. In fact some major providers (Hotmail, Outlook ie Microsoft owned domains) do not allow users to view images sent inline. Apart from attachments, there seems to be better support out there for remote images compared to inline images added with Content-ID or simply as base64 encoded data.

linking to a remote image

The Add image button is the third from right; you enter the url (ie https://server/path_to/file) of the image resource here. All content incidentally, be it paragraphs of text, images or links should be enclosed in a div tag. You can use the code view (</>) to check this, but generally if the email to be sent looks ok, it probably meets this requirement.

Here's how this email appears went sent to JWMA user with 5. allow all images selected:

And here it is at gmail; the account used here is in the standard configuration. I believe gmail allows some configuration changes, including blocking of images, as does JWMA of course. I believe the same applies at Microsoft owned providers such as Hotmail and Outlook, where accounts with the standard configuration will display the image.

Using Content-ID

This is known to be problematical. JWMA now supports it as does gmail and yahoo, but the Microsoft domains do not. As with remote images, even if the provider or the recipients email client accept images, a configuration change may block them. I've not tested what JWMA produces on any of the various desktop email clients and we probably don't know what our recipient uses! In short, there is no way to guarantee inline images, however supplied, will be displayed when the email is read.

The image is added simply by a drag and drop into JWMA's rich text editing area from your graphical file manager. You could also encode the image using the supplied utility (util folder) and add the base64 code into the code view (</>) window. Behind the scenes a Content-ID tag is generated automtically. Only one image can be added, if you add a second image in this way, the result will not be what you expected.

It's probably best to leave the Don't add Content-ID checkbox unchecked. This only has effect if an email has been created that includes a drag and dropped image. If you do check it (this is the third method), no Content-ID tag will be added, but the email will have a rather different structure and this might, in some circumstances, improve the chance that the recipient will see your image. As an example, I know that protonmail users can create email in a similar way, but further research is needed before I can say how useful this option is. JWMA itself will display email with inline images whether or not they were created with a Content-ID tag

Here'sthe email ready to send:

And here it is at gmail. JWMA would display such an email more or less identically if setting 4. in line images only is in place.

Contacts

This allows you to store a list of contacts with email addresses. Clicking on the email address takes you to the compose window, with the To field pre-entered. Selecting a checkbox and pressing the Email contacts button has similar effect, but this has the additional function of placing a list of recipients in the To field if more than a single checkbox is selected.

The list can be filtered by surname using the selector, which will initially be labeled * to indicate that the full list of contacts is displayed.

Delete contacts operates on entries whose checkbox has been selected. Create contact does its work when the firstname, lastname and email fields have been completed.

Managing folders and mailboxes

To create a new top level mailbox type a name such as test in the input field adjacent to the drop down list and press the Create new button. As explained in the Main page section above, some of the following is underlying system specific.

On both mbox and maildir systems you can use the mailbox store separator character, shown on the black bar of the Main page to create a nested mailbox or folder. On a mbox based system test/test in the input field, will create both a new folder and a new mailbox within it, or just a new nested mailbox if the folder already exists. You can create an empty folder without creating a mailbox at the same time by selecting Folder from the drop down list. On a maildir system test.test will only work if there is already a folder test.

On both systems that already have test/test or test.test, after pressing Create new with test/another | test.another in the input field, the single test folder will now contain two mailboxes or folders. You must always use the correct file separator of the underlying system or the result will not be what you expect.

Folders and mailboxes are deleted by checking the appropriate box and pressing the Delete button. Care is needed as without warning all mailboxes / folders nested within a folder are removed As described here, all messages within all deleted folders / mailboxes will be moved to Trash.

Mailboxes and maildir folders with all the messages they contain can be moved around the hierarchy by checking the appropriate box, selecting the folder from the drop down list and pressing the Move to button.

The small screen interface

If you access Jwma using your smart phone, you should be automatically directed to an alternative interface, but as a fall back the login screen of each interface allows you to switch manually. Compared to the desktop interface there are optimizations both in layout and in a reduction of the feature set.

These screenshots where taken from a galaxy 2 running cyanogenmod; the mobile interface looks pretty much the same on the iphone.

A successful login takes you directly to the INBOX rather than a folder listing. The mailbox list is accessible in the same way as on the desktop interface (the first left navigation icon) a major difference being that folders and any mailboxes nested within them (mbox system) and nested folders (maildir) are not accessible. Other differences include the absence of a save draft option, no option to create html mail, message lists are displayed in recent first order and message display being set to plain text (option 2).

There is no contradiction between the two interfaces in that their settings do not clash. Any folders, nested mailboxes (mbox) and nested folders (maildir) you created via desktop access remain untouched by small screen access and if you normally read messages using some setting other than plain text, that setting will remain in place for desktop access.

For the developer

• Tidy up the language files. To add another language, copy a StripesResources properties file in /webmail/web/WEB-INF/classes to StripesResources_xx.properties (where xx is something suitably representative), translating the right hand side of = on each line of the file. Add the appropriate xx to the languages list in jwma.config and rebuild as above.


• There is a second way to enter images by Content-ID, not recommended because the image is not displayed as the email is written and you have to guess at it's height to avoid gmail displaying text that should be below it correctly. You attach the image as you would a normal attachment, but add a cid:xxxx as the image source, with xxxx matching the filename of the image without its extension. You can add up to three images this way. Giving the patchy support for Content-ID it's doubtful if it is worth much effort to make this method more user friendly.


• There is an non minimized version of the rich text editor in the util folder. Unlike the rest of the user interface the rich text editor tool tips are presently resolutely English only.


• As noted in the installation section, building JWMA from source is quick and simple. I can help anyone who wishes to contribute with getting up to speed with stripes (the web framework) and with IntelliJ IDEA integration

Other stuff