XCMailr - Email Service for Testing

A small mailer for us but a big helper for testing

View project onGitHub

XCMailr

Summary

  • Name: XCMailr
  • Version: 1.1.4
  • Release: Sept. 2013
  • License: Apache V2.0
  • License URI: http://www.apache.org/licenses/LICENSE-2.0.txt
  • Tags: AntiSpam, Testutility
  • Contributors:
    • Patrick Thum, Xceptance Software Technologies GmbH
    • Patrick Hähnlein, Xceptance Software Technologies GmbH

Description

XCMailr lets you quickly and easily reduce spam in your email account. Simply create temporary email addresses and have all incoming email forwarded to your actual account. When its configurable lifetime expires, the address gets deactivated and all incoming mail will be silently dropped. XCMailr doesn't store any email content and and won't notify the sender if the address is no longer valid.

Requirements

  • Memcached, optional since V1.1.3 but recommended

Configuration

  • Open and edit the application.conf in conf/ .
  • It is strongly recommended to create a new application secret. This secret ensures that the session-cookie of a user has not been modified.
  • You should especially customize the following settings:
    • application.secret uncomment and set this line, its used to verify session-cookies
    • mbox.dlist the list of available domains
    • mbox.host the main-application-host
    • mail.smtp.* the "outbound" SMTP-Server (the server to which the application will forward any "valid" messages)
    • memcached.* the MemCached-Server (host and port)
    • ebean.* the Ebean-Configuration
  • You can configure the logging by editing conf/logback.xml. See http://logback.qos.ch/manual/ for documentation.
  • HTTPS support, Edit conf/jetty.xml-file as shown here: http://blog.callistaenterprise.se/2011/11/24/quick-start-jettys-maven-plugin-with-ssl/

Run the Application

  • Just rename the application.conf.template to application.conf and edit the application.conf (see Configuration). Then run the 'run.sh'-script.
  • If you set a value for "application.basedir", the server will use that value as contextpath for your application. That means when you specify the value "xcmailr" for the basedir and "http://localhost:8080" as "application.url", then your application can be locally reached at "http://localhost:8080/xcmailr". If you want to run the application behind a reverse proxy, have a look at the section below.
  • To drop and recreate all tables (which will remove all data contained in this tables!), run the script with the parameter "-Dxcmailr.xcmstart.droptables=true".

Build from Source

  • If you want to build the project from the sources, you have two options to run the webapp.
  • First option (after you've changed something and want to check your changes), the development-mode:
    • cd into the 'xcmailr-webapp' folder
    • execute 'mvn clean jetty:run' to clean up the target-folder (if existent) and run the app in development-mode inside an embedded-jetty running on localhost:8080 (the "basedir" will be ignored here)
    • NOTE: The webapp does not check whether the database and the tables exist. On the first run, you must set "%dev.ebean.ddl.run" and "%dev.ebean.ddl.generate" in application.conf to "true" to execute the "create table"-scripts and run the app successfully (afterwards you should set these values to "false" again, otherwise the database will be dropped and recreated after each server-reload).
    • NOTE2 (especially for contributors): You probably want to change the configuration-file in dev-mode. Thereby, you should either set a gitignore (or svn:ignore) to prevent that your personal data (e.g. the mailservice-login) will be committed to the repository or you can place another application.conf at /home/yourUsername/conf/ . The ninja-framework uses Apache Commons Configuration to read the file. It will search for the configuration-file at first in this folder. In both cases you have to take care that the .conf-files at ./xcmailr-webapp/src/main/java/conf and ./xcmailr-resources/conf are up-to-date and contain all necessary keys.
  • Second option (to create the build-folder):
    • cd into the home-directory of XCMailr
    • run 'mvn clean package' to create the build-folder
    • now there will be a folder called 'xcmailr-build' which contains the known files and can be executed as explained in the section "Run the Application"

Using an Apache Reverse-Proxy

  • You may want to use an (Apache2) reverse-proxy in front of the application. With the "application.basedir"-option in the application.conf, you can specify a context-path for your application. Thereby, you can use the same path on which the app will be available through the proxy.
  • For instance, if it will be available externally at "http://reverse.proxy/path/to/app", then you can set the basedir to "path/to/app" and it will run locally at "http://localhost:port/path/to/app".
  • The advantage is that you don't have to use the mod_proxy_html-module to rewrite every link and file-paths on all html-pages.
  • After setting up the Apache2 with all necessary Proxy-Modules (especially you have to enable proxy and proxy_http), you'll have to create a VirtualHost-Configuration for your site. Here's a small example for that:
<VirtualHost *:80>  
    ProxyRequests off  
    ProxyPass /xcmailr/ http://localhost:8080/xcmailr/  
    ProxyPassReverse /xcmailr/ http://localhost:8080/xcmailr/  

    <Proxy http://localhost:8080*>  
        Order deny,allow  
        allow from all  
    </Proxy>  

    Redirect /xcmailr       /xcmailr/  
</VirtualHost>
  • We set the basedir to "xcmailr" and our app then runs locally on "http://localhost:8080/xcmailr", externally it can be reached with this configuration at http://mydomain/xcmailr.

Frameworks/Librarys/Code/etc. Provided by Others

AngularJS

Avaje Ebean

Bootstrap Datetimepicker

H2 Database Engine

Icons by Glyphicons (shipped with Twitter Bootstrap)

Jetty 6

jQuery Tablesorter 2.0 plugin

Spymemcached

JBCrypt - a Java BCrypt implementation

JodaTime

NinjaFramework

Twitter Bootstrap

License

XCMailr is licensed under the Apache Version 2.0 license. See LICENSE file for full license text.