Step 0: Requirements
####################

  * JRE 1.6+
  * root (linux/unix) or Administrator (Windows)
  * libc6 (linux)
  * 512MB RAM (launches with -Xmx512M - can use less, can need more, depending on load)

Step 1: Download
#################

  * Download apache-james-3.0-beta4-app.zip from http://james.apache.org/download.cgi#Apache_James_Server

Step 2: Deploy
##############

  * Unzip apache-james-3.0-beta4-app.zip.
  * You should have a folder with sub-folders bin, conf, lib, log, var and four text files.

$ unzip japache-james-3.0-beta4-app.zip
$ cd apache-james-3.0-beta4-app
$ ls (linux) / dir (windows)
bin
BUILD.txt
conf
lib
LICENSE.txt
log
NOTICE.txt
README.txt
var

Step 3: Understand James Features
#################################

Persistence
- Mailbox is for users' Inbox, Sent Items, Trash... folders - Mailbox persistence is configured in spring-beans.xml (by default jpa, you set the database connection properties in database.properties - can also be maildir=file, jcr). We think to move this config out-of spring-beans.xml.
- Mailrepositorystore is for spam, error,... mails, so nothing to do with users visible mails. Available mailstore persistence are defined in mailstore.xml. Each has an URL prefix (file, db, dbfile,...) that can be used in mailetcontainer.xml to define where to store spam,... mails (exemple: file://var/mail/error/).
- Domain persistence is configured in domainlist.xml
- Users persistence is configured in usersrepository.xml
- All database connection use the database.properties in case of database access.

Mailet Container - http://james.apache.org/server/3/feature-mailetcontainer.html

SMTP Hooks - http://james.apache.org/server/3/feature-smtp-hooks.html

Step 4: Configure
#################

  * All configuration files are embedded in jars.
  * We ship in the conf folder template configuration files.
  * You can override the default configuration : 
      Copy the conf folder any ...-template... you need and update according to your needs.

database.properties
META-INF/persistence.xml
dnsservice.xml
domainlist.xml
fetchmail.xml
imapserver.xml
james-listmanager.xml
jcr-repository.xml
jmx.properties
lmtpserver.xml
log4j.properties
mailetcontainer.xml
mailbox.xml
mailserver.xml
mailrepositorystore.xml
pop3server.xml
recipientrewritetable.xml
smtpserver.xml
sqlResources.xml
usersrepository.xml
wrapper.xml
lib folder (for your additional jar, e.g. JDBC drviers,...)

James is packaged with virtual hosting enabled, JPA (Derby database) storage for the mails, users, and domains.
On SMTP (see smtpserver.xml config)
  * authRequired is true by default, so you can safely deploy James on the Internet (it won't be an open relay).
  * verifyIdentity is true by default (you can only send mails with a FROM being the authenticated user).

To use another database:
  * Edit the database.properties and change the values according to your database.
  * Add the needed JDBC driver jar in the ./conf/lib folder according to your database.
  
Step 5: Start
#############

$ cd bin
$ ./james start 
  * !! you need libc6 installed on Linux !! - sudo apt-get install libc6-i386 libc6-dev-i386 on ubuntu
  * You can see log result in the log/james-server.log file.

Step 6: Create Domains and Users
################################

Time to add domains and users.
We will show how to via the james-cli (client interface).
You also can achieve this via JMX (launch jconsole). JMX has more operations tha james-cli.

  * cd bin
  * james-cli -h localhost -p 9999 adddomain mydomain.tld
  * james-cli -h localhost -p 9999 adduser myuser@mydomain.tld mypassword

  * The username to use in your mail client will be myuser@mydomain.tld

Step 7: Test
############

$ telnet 127.0.0.1 25
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 172.16.1.131 SMTP Server (JAMES SMTP Server 3.0-beta4) ready Sat, 6 Nov 2010 17:31:33 +0100 (CET)
ehlo test
250-172.16.1.131 Hello test (aoscommunity.com [127.0.0.1])
250-PIPELINING
250-ENHANCEDSTATUSCODES
250 8BITMIME
mail from:<YOUR_NAME@YOUR_DOMAIN>
250 2.1.0 Sender <YOUR_NAME@YOUR_DOMAIN> OK
rcpt to:<YOUR_NAME@YOUR_DOMAIN>
250 2.1.5 Recipient <YOUR_NAME@YOUR_DOMAIN> OK
data
354 Ok Send data ending with <CRLF>.<CRLF>
subject: test

this is a test
.
250 2.6.0 Message received
quit
Connection closed by foreign host.

Step 8: Manage
##############

8.1. Manage via james-cli

  usage: java org.apache.james.cli.ServerCmd --host <arg> <command>
    -h,--host </arg>   node hostname or ip address
    -p,--port </arg>   remote jmx agent port number
  Available commands:
    adduser </username> </password>
    removeuser </username>
    listusers
    adddomain </domainname>
    removedomain </domainname>
    listdomains

8.2. Manage via JMX

  * Launch jconsole (or any other JMX client) and connect on URL=service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi
  * Select the MBeans tab and open the org.apache.james node to view attributes and execute operations.

Step 9: Monitor
###############

  * Monitor the ./log/james-server.log log file.

  * Monitor via JMX (launch any JMX client and connect to URL=service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi)

  * Check ./var folder usage
  
    mail
    +-error
    +-address-error
    +-relay-denied
    +-spam

    store
    +-maildir
    +-derby
    +-jackrabbit
    +-activemq
      +-brokers
        +-james
      +-blob-transfer
        +-outgoing
        +-spool

  * Check /tmp folder usage