Skip to end of metadata
Comment: Recommend Java 7 over Java 6
Go to start of metadata

To start developing web applications with AppFuse, please following the instructions below:

Table of Contents

  1. Create a new project.
  2. Run it.
  3. Have Fun.

Create a project

  1. Setup your Development Environment - or follow the steps below if you're a veteran.
    1. Download and install JDK 7+ (make sure your JAVA_HOME environment variable points to the JDK, not a JRE).
    2. Download and install MySQL 5.5+ (or use a different database see here).
    3. Setup a local SMTP server or change mail.properties (in src/main/resources) to use a different host name - it defaults to "localhost".
    4. Download and install Maven 3.0.4+.
  2. From the command line, cd into your "Source" directory (c:\Source on Windows, ~/dev on Unix) run the Maven command you see below after choosing your web framework and other options.
Choose your Stack

AppFuse comes in a number of different flavors. To optimize and simplify your experience as a user, we've created a number of different archetypes (a.k.a. starter projects). There are currently three types of AppFuse Archetypes: light, basic and modular. Light archetypes are bare-bones, basic archetypes contain User Management and Security and modular archetypes contain "core" and "web" modules and are ideal for creating projects that have a re-usable backend. You should change the groupId to match your preferred package name and the artifactId to match your project's name.

The warnings you see when creating your project are expected. If you see BUILD SUCCESS at the end, your project was created successfully.

You should be able to run AppFuse immediately if you have a MySQL 5.x database installed and it's accessible to root using no password. If you'd prefer to use an embedded database, we've recently added Database Profiles for H2, HSQLDB, etc.

Run your application

Running AppFuse is easy now. Once the archetype project is created, Maven will create and populate your database using the hibernate3 and dbunit plugins, respectively. All you have to do is use Maven to run the Jetty container and view your application.

  1. Decide if you want to change AppFuse from "embedded mode" to full-source mode by running mvn appfuse:full-source from your project's root directory. Embedded mode means the service layer is contained in JARs vs. having the source in your project.

  2. To view your application run mvn jetty:run from your project's directory (for a modular project, you'll need to run mvn jetty:run from your project's web directory (after installing the core module)). Maven will start Jetty and you should be able to view your application in your browser at http://localhost:8080.

  3. Check your new project into source control, unless you have a good reason not to. Google Code, GitHub, and BitBucket are good options.

  4. Run mvn from within your project to download JARs, Tomcat and run the integration tests in your project.

    The default username/password for an admin user is admin/admin. For a regular user, use user/user.

If you receive OutOfMemory errors when using mvn jetty:run, increase the memory available to Java. For example, set your JAVA_OPTS environment variable to -Xmx1024M -XX:PermSize=512m.

Changing database settings

To change your MySQL database settings, simply change the <jdbc.*> properties at the bottom of your pom.xml. See Database Profiles to use a database other than MySQL.

MySQL Security

Running MySQL using root with no password is not the most secure thing to do. Once your database is created, you can change the root password using the command below:

mysql --user=root --pass='' mysql -e "update user set password=password('newpw') \
where user='root'; flush privileges;"

AppFuse uses the username "root" and a blank password by default. To change these values, modify the <jdbc.username> and <jdbc.password> properties in your project's pom.xml (at the bottom).

If your pom.xml doesn't contain existing properties, you can fix this by adding them just before the closing </project> tag as follows:

<properties><jdbc.password>yourmysqlrootpw</jdbc.password>

Develop your application

You can develop your application using Eclipse, IDEA or NetBeans. For Eclipse, install m2e and import your project. For IDEA, simply use File > Open Project and point to your project's directory. Further instructions can be found in the IDE Reference Guide.

The Tutorials should help you get started developing your application.