| Apache James Project |
| ==================== |
| |
| link:https://gitter.im/apache/james-project[image:https://badges.gitter.im/apache/james-project.svg[Join the chat at link:https://gitter.im/apache/james-project]] |
| |
| image::james-logo.png[James logo] |
| |
| == What is James? |
| |
| *James* stands for *Java Apache Mail Enterprise Server!* |
| |
| It has a modular architecture based on a rich set of *modern* and *efficient* components which provides at the end |
| *complete, stable, secure and extendable Mail Servers running on the JVM*. |
| |
| Create your *own personal solution* for emails treatment by assembling the components you need thanks to the Inversion |
| of Control mail platform offered and go further customizing filtering and routing rules using *James Mailet Container*. |
| |
| Supported protocols are: IMAP, SMTP, JMAP, POP3 and more... |
| |
| Read more on https://james.apache.org/[our website]. |
| |
| == How to contribute? |
| |
| James is a project that lives from the contributions of its community! Anyone can contribute! |
| |
| Read the https://james.apache.org/contribute.html[contributing guidelines]. |
| |
| We more than welcome *articles* and *blog posts* about James. Contact us by https://james.apache.org/mail.html[email] |
| or on https://gitter.im/apache/james-project[Gitter] to share your experiences. |
| |
| *Documentation* is an easy way to get started, and more than wanted! Check out the https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20documentation%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~documentation] label on JIRA. |
| |
| And to get started with *code contributions*, search out the |
| https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20newbie%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~newbie], |
| https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20easyfix%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~easyfix], |
| https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20feature%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~feature] labels on JIRA. |
| |
| There is many other ways one can help us: packaging, communication, etc ... |
| |
| = How to... |
| |
| * link:#how-to-try-james[How to try James] |
| * link:#how-to-check-the-compilation[How to check the compilation] |
| * link:#how-to-run-james-in-docker[How to run James in Docker] |
| ** link:#run-james-with-guice-%2Dcassandra-%2Drabbitmq-%2Ds3-%2Delasticsearch[Run James with Guice + Cassandra + RabbitMQ + S3 + ElasticSearch] |
| ** link:#run-james-with-guice-%2Dcassandra-%2Delasticsearch[Run James with Guice + Cassandra + ElasticSearch] |
| ** link:#run-james-with-guice-%2Djpa-%2Dlucene[Run James with Guice + JPA + Lucene] |
| ** link:#run-james-with-spring-%2Djpa[Run James with Spring + JPA] |
| * link:#other-useful-commands[Other Useful commands] |
| ** link:#how-to-add-a-domain-[How to add a domain?] |
| ** link:#how-to-add-a-user-[How to add a user?] |
| ** link:#how-to-manage-sieve-scripts-[How to manage SIEVE scripts?] |
| ** link:#how-to-retrieve-users-and-password-from-my-previous-container[How to retrieve users and password from my previous container?] |
| * link:#develop-on-james[Develop on James] |
| ** link:#how-to-run-deployment-tests[How to run deployment Tests] |
| ** link:#how-to-check-the-merge-of-a-commit[How to check the merge of a commit] |
| * link:#know-more-about-james-design[Know more about James design] |
| * link:#articles-for-james-community[Articles for James community] |
| ** link:#how-to-build-and-publish-the-website[How to build and publish the website] |
| ** link:#how-to-release-via-maven-release-plugin[How to release via maven release plugin] |
| |
| == How to try James |
| |
| Requirements: docker & docker-compose installed. |
| |
| When you try James this way, you will use the most current state of James. |
| It will be configured to run with Cassandra & ElasticSearch. |
| All those three components will be started with a single command. |
| |
| You can retrieve the docker-compose file : |
| |
| $ wget https://raw.githubusercontent.com/apache/james-project/master/server/apps/distributed-app/docker-compose.yml |
| |
| Then, you just have to start the services: |
| |
| $ docker-compose up |
| |
| Wait a few seconds in order to have all those services start up. You will see the following log when James is available: |
| james | Started : true |
| |
| A default domain, james.local, has been created. You can see this by running: |
| |
| $ docker exec james java -jar /root/james-cli.jar -h 127.0.0.1 -p 9999 listdomains |
| |
| James will respond to IMAP port 143 and SMTP port 25. |
| You have to create users before playing with james. You may also want to create other domains. |
| Follow the 'Useful commands' section for more information about James CLI. |
| |
| |
| == How to check the compilation |
| |
| In order to have a standard compilation environment, we introduce Dockerfiles, using java-11. |
| |
| === Maven |
| |
| We require maven version 3.6.0 minimum to build the project. |
| |
| Simply run `mvn clean install` within this directory to compile the project. |
| |
| Useful options includes: |
| |
| - `-DskipTests` to skip the long to execute resource consuming test suite that requires a docker daemon. |
| - `-T 4` to parallelize the build on several CPUs. |
| |
| == How to run James in Docker |
| |
| This feature is available for three configurations : |
| |
| * link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/README.adoc[Guice + Cassandra + RabbitMQ + S3 + ElasticSearch (distributed)] |
| * link:https://github.com/apache/james-project/blob/master/server/apps/cassandra-app/README.adoc[Guice + Cassandra + ElasticSearch] |
| * link:https://github.com/apache/james-project/blob/master/server/apps/jpa-app/README.adoc[Guice + JPA + Lucene] |
| * link:https://github.com/apache/james-project/blob/master/server/apps/memory-app/README.md[Guice + Memory (testing)] |
| |
| == Using the CLI |
| |
| See https://james.apache.org/server/manage-cli.html[Manage James via the Command Line] for more info. |
| |
| === How to add a domain ? |
| |
| # Add DOMAIN to 127.0.0.1 in your host /etc/hosts |
| $ docker exec james_run java james-cli -h 127.0.0.1 -p 9999 adddomain DOMAIN |
| |
| DOMAIN: is the domain you want to add. |
| |
| Note: Using docker, one can add an environment variable holding the domain to be created. This |
| domain will be created upon James start: |
| |
| $ --environment DOMAIN=domain.tld |
| |
| === How to add a user ? |
| |
| $ docker exec james_run java james-cli -h 127.0.0.1 -p 9999 adduser USER_MAIL_ADDRESS PASSWORD |
| |
| Where : |
| |
| * USER_MAIL_ADDRESS: is the mail address that will be used by this user. |
| * PASSWORD: is the password that will be used by this user. |
| |
| You can then just add DOMAIN to your /etc/hosts and you can connect to your james account with for instance Thunderbird. |
| |
| === How to manage SIEVE scripts ? |
| |
| Each user can manage his SIEVE scripts through the manage SIEVE mailet. |
| |
| To use the manage SIEVE mailet : |
| |
| * You need to create the user sievemanager@DOMAIN ( if you don't, the SMTP server will check the domain, recognize it, and look for an absent local user, and will generate an error ). |
| * You can send Manage Sieve commands by mail to sievemanager@DOMAIN. Your subject must contain the command. Scripts needs to be added as attachments and need the ".sieve" extension. |
| |
| To activate a script for a user, you need the following combination : |
| |
| * PUTSCRIPT scriptname |
| * SETACTIVE scriptname |
| |
| === How to retrieve users and password from my previous container |
| |
| Some james data (those non related to mailbox, eg : mail queue, domains, users, rrt, SIEVE scripts, mail repositories ) are not yet supported by our Cassandra implementation. |
| |
| To keep these data when you run a new container, you can mount the following volume : |
| |
| -v /root/james-server-app-3.0.0-beta6-SNAPSHOT/var:WORKDIR/destination/var |
| |
| Where : |
| |
| * WORKDIR: is the absolute path to your james-parent workdir. |
| |
| Beware : you will have concurrency issues if multiple containers are running on this single volume. |
| |
| == Develop on James |
| |
| James requires at least JDK 11 and Maven 3.6.0 to build. |
| Some parts of James are written in Scala so one might need to enable Scala plugin in IDE. |
| |
| === How to run deployment Tests |
| |
| We wrote some MPT (James' Mail Protocols Tests subproject) deployment tests to validate a James |
| deployment. |
| |
| It uses the External-James module, that uses environment variables to locate a remote |
| IMAP server and run integration tests against it. |
| |
| For that, the target James Server needs to be configured with a domain domain and a user imapuser |
| with password password. Read above documentation to see how you can do this. |
| |
| You have to run MPT tests inside docker. As you need to use maven, the simplest option is to |
| use james/parent image, and override the entry point ( as git and maven are already configured |
| there ) : |
| |
| $ export JAMES_ADDRESS=127.0.0.1 |
| $ export JAMES_IMAP_PORT=143 |
| $ export JAMES_SMTP_PORT=25 |
| |
| $ mvn -T 1C -DskipTests -pl org.apache.james:apache-james-mpt-external-james -am install |
| $ mvn -T 1C -pl org.apache.james:apache-james-mpt-external-james test -Pintegration-tests\ |
| |
| Where : |
| |
| * JAMES_IP: IP address or DNS entry for your James server |
| * JAMES_IMAP_PORT: Port allocated to James' IMAP port (should be 143). |
| * JAMES_SMTP_PORT: Port allocated to James' SMTP port (should be 25). |
| |
| == Know more about James design |
| |
| James comes with a https://james.apache.org/documentation.html[Documentation] and https://github.com/linagora/james-project/tree/master/src/adr[Architectural Decision Records]. |
| |
| == Articles for James community |
| |
| * link:docs/modules/community/pages/website.adoc[How to build and publish the website] |
| * link:docs/modules/community/pages/release.adoc[How to release via maven release plugin] |
