YANOCC Documentation
--------------------


Copyright 2001 Julien Tessier <jt@chezjulien.com>
Some parts:
    Copyright 2000 Nicolas Chalanset <nicocha@free.fr>
    Copyright 2000 Olivier Cahagne <cahagn_o@epita.fr>

Summary
*******

This file contains the following sections:
	* Overview of Yanocc
	  - License
	  - Getting Nocc
	* Requirements for YANOCC
	* Installing YANOCC
	* Additional notes for YANOCC
	  - History

Overview of Yanocc
******************

   Yanocc is a Web-based e-mail reader. It uses PHP and a Web server to access
a mail server (POP3, IMAP) and send e-mail (SMTP or plain sendmail).

   Yanocc is based on Nocc's code (http://nocc.sourgeforge.net/) and you must
keep in mind that this early release of Yanooc is very near to Nocc.

   Yanocc can be used as an e-mail reader and allows you to view, send messages,
manage your mail account. It can view and send MIME attachments (files, HTML,
etc.).

   Yanocc has low requirements on browser, it uses JavaScript as less as
possible, nearly no frames and even works with Lynx without cookies; low
requirements on Web servers too: you don't need any superuser privileges to
install Yanocc and it can work with suEXEC (see Apache documentation) for
increased security.

   Anybody is encouraged to contribute.

  License
  -------

   The full application (source code, icons) is distributed under the terms of
the GNU General Public License. See the file COPYING for details.

  Getting Yanocc
  ------------

   Yanocc development is powered by the free services offered by SourceForge to
the Open Source community. The Web page of Yanocc is http://yanocc.sourceforge.net/

   The latest release can always be found on SourceForge and is available from
'http://sourceforge.net/projects/yanocc/'.

  Reporting bugs, sending suggestions or contributions
  ----------------------------------------------------

   We welcome bug reports or suggestions for Yanocc at the Web-based bug tracker
from SourceForge available at 'http://sourceforge.net/bugs/?group_id=34256'.

Requirements
************

  Mandatory Items
  ---------------

   * PHP 4.0.0 or later with IMAP support (--with-imap) -- SEE NEXT SECTION
  
   * A Web server supported by PHP (i.e. Apache for most people)
  
   * An IMAP or POP3 server to connect to.

  Optional Items
  --------------

   * An SSL Web server to allow encrypted connections.
     (Apache+mod_ssl+OpenSSL is popular)

  Notes on PHP
  ------------

   * PHP needs to be compiled with IMAP support. (--with-imap at the configure
     stage).
     You'll find information on IMAP support for PHP at
     'http://www.php.net/manual/ref.imap.php'.

Installing YANOCC
*****************

  Installation of YANOCC
  --------------------
       
       1) Download yanocc-x.y.tar.gz (where x and y are version numbers)
	  (or yanocc-x.y.zip for Windows' users).
	  http://yanocc.sourceforge.net/

       2) untar/unzip yanocc into the directory you want.
	  Default directory is yanocc.
      
       3) Change into the 'yanocc' directory, make changes to the 
          config file (conf.php.dist) and save the new one to conf.php
	  (remove .dist in the file name)

           'conf.php.dist' contains a large number of default values
           that you'll need to configure for your system, such as
           the default IMAP/POP3 server, whether or not users can pick a
           different server, etc...
	   The file is fairly well documented, so you should be able to pick
	   out what you need to change fairly easily.

       4) (Optional step)
	  if you run with suEXEC, you'll need to run './addcgipath path' to add
	  the parser line at the beginning of PHP files.

       5) Remove ./addcgipath.sh. For security reasons, it might be run by
          external users although "sh" files are never interpreted by Web
          servers with default configuration.

Additional notes
****************

  Known working setups
  --------------------

   YANOCC has been tested with:

	* servers: (Yanocc should work with any server, however, these have been
specifically tested and are known to work)
	  - Apache with PHP compiled as module or CGI.
	  - Apache 1.3.12, 1.3.14, 1.3.17, 1.3.19, 2.0.14 (Win32).
	  - Microsoft IIS 4.0, IIS 5.0 w/CGI, IIS 5.0 w/ISAPI.
	  - O'Reilly WebSite Pro 2.x & 3.
	  - PHP 4.0.0, 4.0.1, 4.0.1pl1, 4.0.2, 4.0.3pl1, 4.0.4, 4.0.4pl1.
	  - PHP running through a wrapper: suEXEC.
	  - various OS including GNU/Linux, FreeBSD, NetBSD, OpenBSD and Win2k.
	  - PHP 4.0.4-dev compiled as module for Apache Win32.
	  - warning: due to a sessions bug, only PHP 4.0.4 or higher will run
	    correctly on Win32 platforms.

	* browsers: (256 colors setups are ok)
	  - Netscape 4.x, 6.x for Unix and Windows.
	  - IE 4.x, 5.x for Windows.
	  - Lynx 2.8.3, Konqueror, Opera, WebTV 3.0.
	  - Mozilla 0.x for Linux and Windows.
	  - with or without cookies.

	* mail servers: (Yanocc should work with any IMAP/POP3 server, however,
these have been tested and work)
	  - UCB POP3 1.831beta.
	  - MS Exchange 5.5 Build 2650-24 Service Pack 3.
	  - Default RedHat 6.1 IMAP daemon v.12.250 (perhaps Cyrus IMAPd ?).

        * MTA: (Yanocc should work with any MTA, however, these have been tested
and work)
	 - Sendmail.
	 - Postfix.

   YANOCC has been used for many months at:

	* a company with approx. 150 unique users/day,
	* a school with also 150 unique users/day.

  Tips
  ----

   Enhance randomization with PHP by uncommenting the entropy lines if your OS
has this feature (known to work with NetBSD and Linux for e.g.).
   See PHP manual, this is used for session numbers, creating temporary files,
etc.

  Yanocc history (by Julien Tessier)
  ----------------------------------

   Wanting to open a free webmail service, I discovered NOCC. Powerful, fast and
easy-to-use. But some features were missing: address book, folders, etc.
Implementing such features would require the use of a database, what NOCC's
authors don't want. That's why I started the project of YANOCC (Yet Another
NOCC).

  Nocc history (by Olivier Cahagne)
  ---------------------------------

   NOCC started as Epimail, a Webmail for our school as a free project.
   The first version was written in Perl because it was powerful, object
features, adapted to the Web and available in our school. It also didn't
require any superuser privileges.

   Webmail clients we found either required database support, superuser
privileges or an IMAP server. We had neither of these and we wanted to have
something quite simple to access a POP server and an SMTP server.

   The Perl version was nice and is now released for your pleasure in GPL (some
people already actually committed patches) but it won't work out-of-the-box, we
don't have time to write doc neither maintain it anymore).

   We started working on Epimail in May 1999 and had it working in July 1999,
it's been working for more than 1 year with approx. 150 unique users per day.
The projects has also been used by two companies through some friends who came
to know it.

   The problem was that it was our first big software written in Perl, and we
didn't write it very well, mixing code and HTML, so it was hardly maintainable.
Meanwhile, I discovered PHP and started rewritting it with PHP but lacked SMTP
support so sendmail was required. Then submitted my work to Nicolas Chalanset
who made a working version by adding proper session feature, etc. and actually
used it for a company.

   We decided to make a maintainable and public version under GPL so that it
can be simple to setup, have POP and SMTP features, MIME decoding features.


----------------------------------------------------------------------
We hope you find YANOCC useful and easy to use.  We thank you for taking
the time to try it and if you ever have any questions, just drop a note on
<yanocc-discuss@lists.sourceforge.net>

Enjoy,

The YANOCC team
----------------------------------------------------------------------
