Welcome to Lichen 0.3!

Lichen aims to be a sophisticated but easy-to-use IMAP client, powered by AJAX and PHP.

We wrote Lichen because we wanted to check e-mail from a Web browser, but with the fun and excitement of fashionable techniques like AJAX. To avoid over-complicating our lives, we've tried to make it as easy to set up as possible, while providing an experience just as good as commercial e-mail services, and all released under the GPL.

This is a pre-release version of Lichen; you shouldn't install it on a production server.

Server requirements

• An IMAP server that has your mail (such as  Dovecot)
• A Web server (such as  Apache)
•  PHP version 4.4 or higher; we recommend using PHP 5.2
• Your PHP must have IMAP support built-in. On most Linux distributions, this means installing the package called php-imap (e.g. on Debian, run apt-get install php-imap as root).

Getting started

To install Lichen, you'll need:

• A Web server and IMAP server meeting the requirements above.
• Some method of getting Lichen on to your Web server, such as an FTP client.
• A text editor, to edit the configuration file.
• A modern Web browser: Firefox 1.5+, Safari 2+, and Internet Explorer 6+ are supported in this release. (Opera and Konqueror support is forthcoming.)

1. Download and unpack Lichen

If you're reading this, you've probably already done this step. The latest release can be downloaded from  http://lichen-mail.org and can be decompressed with any program that handles bzip2 (in a shell, just type tar -jxf lichen-0.3.tar.bz2).

2. Create a data directory

Lichen needs somewhere to store your settings and any attachments you send. (Without a data directory, Lichen may still run, but with PHP warnings and no sending ability.)

You should choose a directory that isn't inside your Web root -- i.e. it should not be visible to someone visiting your site. If you're running Lichen on a dedicated system, you could create a directory such as /var/run/lichen.

If you must put Lichen's data in a subdirectory that is visible to your site's visitors (for instance, if your shared hosting only provides access to the Web root), then you should take steps to hide your configuration files. If you're using Apache (most shared hosts are), create a file called .htaccess inside the data directory, with this in the file:

Order Deny, Allow
Deny from all

After saving the file, visit the directory you created with your Web browser to make sure access is denied.

Either way, you must change permissions on the directory to allow the Web server to write there. This is usually done by changing the permissions on the directory to 777 with your FTP client (or by typing chmod 777 /path/to/data in a shell). Alternatively, if you know which user your Web server process runs under (such as httpd), set that user as the owner of the directory (e.g. with chown httpd:httpd /path/to/data).

3. Edit lichen-config.php

Rename the file lichen-config-example.php to lichen-config.php, and open it in a text editor.

Of the options in this file, the most important are the four at the top:

$SMTP_SERVER

This is the outgoing SMTP server with which you send e-mail. If you're using a shared Web host, it'll probably be localhost.

$SMTP_DOMAIN

This is the domain name of your e-mail server as it appears to the Internet. Generally, you should set this manually to be the part after @ in your e-mail address. The default value is to auto-detect the domain of your Web server and assume your e-mail domain is the same, but this won't apply in all cases.

$LICHEN_DATA

This is the directory that you chose for data storage in step 2 above. It's safer to enter a full path if you have it, but a path relative to the Lichen install will usually also work.

$IMAP_SERVER

This is the IMAP server that stores e-mail sent to you. If you're using a shared Web host, this will also probably be localhost.

When you're done, save the file. If you have special needs, or encounter problems, check the section on advanced settings below.

4. Move Lichen to its permanent home

If you normally upload files to your host via FTP, log in with your FTP client and upload the lichen directory into your normal location for Web pages (it'll take a few minutes). If you're working directly on the server, mv the directory into your Web root.

5. Visit the URL and log in

Pop open your Web browser and visit the URL of the location where you installed Lichen. For instance, if you uploaded the directory with Lichen's files to your highest-level Web directory, visit http://yoursite.com/lichen/

You should see a login screen with a picture of an envelope; type in your e-mail username and password and hit Login. If you can see your mailboxes and messages, then you're done!

Advanced settings

By default, Lichen will use an unencrypted SMTP connection on port 25 to send mail. To read mail, it defaults to an SSL-encrypted IMAP connection if your IMAP server is not localhost, and an unencrypted IMAP connection if it is. You can change this behaviour by editing the advanced settings in lichen-config.php:

$SPECIAL_FOLDERS

This array stores the names of the mailboxes that Lichen will use to save your sent messages, unsent drafts, and deleted messages, respectively.

$IMAP_PORT

If this value is non-zero, Lichen will connect to your IMAP server on this port. Otherwise, the port is automatically set to 993 for SSL connections and 143 for unencrypted connections.

$IMAP_FORCE_NO_SSL

If you set this to true, Lichen will not use SSL to connect to your IMAP server. If it's false, Lichen will automatically disable SSL for local connections, and enable it for non-local connections.

$IMAP_USE_TLS

If this is set to true, Lichen will encrypt all connections to the IMAP server with TLS, even to the local host. You should also set $IMAP_PORT (generally to 143) if you turn on TLS.

$IMAP_CHECK_CERTS

PHP's IMAP extension will check the trust level of encryption certificates by default if SSL or TLS are in use. Set this to false if you have a self-signed certificate (or just want to disable trust checking).

$SMTP_PORT

This is the port on which Lichen will connect to your SMTP server. If you use SMTP over SSL you'll need to set this to 465, and if you use Lichen on a home Internet connection you may need to set it to some value other than 25.

$SMTP_USE_SSL

If this is set to true, Lichen will use SSL when sending mail through your SMTP server.

$SMTP_AUTH

In most cases, SMTP servers require you to send your username and password before you can send mail. If your server doesn't require this, set $SMTP_AUTH to false. (If you're setting up an SMTP server and disable authentication, be careful not to create an  open relay.)

$DATE_FORMAT_NEW

This is the  PHP date format string used for messages less than three days old, when displaying a list of messages in a mailbox. (However, this isn't currently used.)

$DATE_FORMAT_OLD

As above, used in the list for messages older than three days.

$DATE_FORMAT_LONG

The full date format used when you view the contents of a message.

$UPLOAD_ATTACHMENT_MAX

This value is inserted into the "compose new message" form as a hint to the browser indicating the maximum accepted size of uploaded files. However, it is a recommendation only -- the actual upload limits are set by the values in your server's  php.ini file.

$DEFAULT_SETTINGS

This array value allows you to override Lichen's default settings for new users, such as if you're running a large custom mail server. See the source of include/settings.inc.php for possible values to insert here.

Known issues / TODOs

• Switching between mailboxes too quickly causes the interface to lose track of which mailbox you're viewing (you'll have to navigate to another page).
• The window flickers when you switch mailboxes.
• TLS support is incomplete -- viewing attachments and sending messages won't work.
• There is no address book.
• We have rudimentary theme support, but it's neither finished nor documented.
• i18n is incomplete; the interface is English-only for now.
• In the settings screen, the sending identities editor and the mailbox manager are incomplete and not particularly robust.
• The clickable list of mailboxes hides mailbox names that are too long.
• There are still a few display issues with high-byte characters that aren't UTF-8.
• Large parts of the code, such as the PHP that generates the new message composer, are temporary hacks that need to be reorganised or cleaned up.
• Your browser's Back button won't work in Lichen.