EmForge Setup Guide

After installing EmForge from war, it is already possible to use it. But, not sure it is really good idea to use default configuration of EmForge for production environment.

By default, EmForge configured for easy-to-use, so, any user will easily able to start use it. But, this default configuration has some problems with performance and security, you will need to fix before try to use it in production.

Some common notes about EmForge Configuration

So, you want to configure EmForge for your own needs, but how to do it? Currently, EmForge has no any Admin-Panel with comfortable GUI to easily do it from your browser. Sorry - we just had no time to do it yet, but we hope to develop it sometimes in future release.

So, to configure EmForge you will need to edit configuration files in your preferred text-editor.

Main Configuration Files you will need to work with:

• ${tomcat.dir}/webapps/EmForge/WEB-INF/classes/config.properties - common configuration file
• ${tomcat.dir}/webapps/EmForge/WEB-INF/classes/META-INF/emforge-ds.xml - SpringFramework configuration file to setup Data-Source, used by EmForge
• ${tomcat.dir}/webapps/EmForge/WEB-INF/classes/META-INF/emforge-security.xml - Spring Configuration file to setup security options.

So, you can find all configuration file under your Tomcat (or any other J2EE server) in directly, there EmForge was deployed. After changing this configuration files, please, do not forgot to restart web-application.

Directory ${tomcat.dir}/webapps/EmForge/WEB-INF/classes/META-INF/ has some other Spring-configuration files, you probably will need to use, but we hope at this moment these 3 files will be enough.

If you will have any questions - always feel free to ask in EmForge Mail Lists - hope we will able to answer.

Remove default admin login

First of all you will need to remove at all - or change password for admin login.

Change password for admin login, you need to find followed block in emforge-security.xml:

<bean id="inMemoryDaoImpl" class="ru.emdev.EmForge.security.memory.MemoryUserDetailsService">
    <property name="userMap">
        <value>
            admin=admin,dummy@emforge.org,admin,ROLE_EMFORGEUSER,enabled,ROLE_EMFORGEADMIN
         </value>
    </property>
</bean>

and change it to

<bean id="inMemoryDaoImpl" class="ru.emdev.EmForge.security.memory.MemoryUserDetailsService">
    <property name="userMap">
        <value>
            admin=XXX,dummy@emforge.org,admin,ROLE_EMFORGEUSER,enabled,ROLE_EMFORGEADMIN
         </value>
    </property>
</bean>

where XXX - is new password.

To remove this login at all - you will need remove line

<ref bean="testDaoAuthenticationProvider"/>

from authenticationManager bean and remove line

<ref bean="inMemoryDaoImpl"/>

from agreegatingService bean

As soon as you will remove default admin user, you will need to give admin rights to some other users. For doing it you will need:

1. Open in any preferred SQL Manager database, used by EmForge (by default it is build-in HSQL);
2. Find roleid of role with name ROLE_EMFORGEADMIN in emfrg_role table;
3. Find userid of required user in emfrg_user table
4. Insert new record into emfrg_user_role table with using found roleid and userid

Configure EmForge to use another SVN Repository

By Default, EmForge is configured to use http://svn.emforge.org/svn/emforge repository to view in Source-Browser Tab.

If you want to change it to your own repository - simple edit line

repository.path=http://svn.emforge.org/svn/emforge

in config.properties

Configure EmForge to use another database.

By default, EmForge is used build-in HSQL. It is simplest database, not very good for production environment, but - using of HSQL is not required any additional steps for configuration to start use EmForge.

If you want to use EmFoge with your own database, you need to change followed settings in config.properties:

• datasource.driver - should contain JDBC driver class-name you want to use. To make it possible for EmForge to find this class, you need to put required jar-file with DB driver into EmFogre's lib: ${tomcat.dir}/webapps/EmForge/WEB-INF/lib or into web-server lib-directory
• datasource.url - should contain JDBC-Url, pointed to your database (including username & password options)
• datasource.dialect - should contain Hibernate Dialect

You can use build-in auto-detection dialect (we go it's sources from LifeRay Portal: com.liferay.portal.spring.hibernate.DynamicDialect - in this case Hibernate Dialect will be auto-detected.

After you will run EmForge next time, it will create all required tables and initial data in this new database.

Configure EmForge to use Data Source

Another way to configure EmForge to use another database - is to use some Data-Source, already configured in you J2EE Server.

To do it - you need to replace emforge-ds.xml with file, attached to this page, and change config.properties so, database.url will contain name of the required DS. For example. under Tomcat, if you have configured jdbc/EmForge data-source, you need to change your config.properties to:

datasource.url=java:comp/env/EmForgeDS

datasource.driver is not make sense in this case (since driver is configured by J2EE server itself). You will need to configure datasource.dialect as well as was already described.

Email Configuration

EmForge sending some emails during processing workflow. For example, then some step is assigned to some user - this user will receive notification email with link to the task.

To configure EmForge for your email settings you need to change email.host property in config.properties to point to your smtp-server (default is localhost)

SMTP with authentication is not currently supported :(

Other security properties

Some other security properties you can use to configure in config.properties:

• security.useAccountActivation - is account activation required. If it is set to true, user account, registered via register.faces will not be actived by default. User will receive email tot he address, used during registration with activation link. Only after clicking on this link, user account will be activated and user will able to login
• security.registerAllowed - is registration allowed. In some cases (for example then LDAP or ActiveDirectory is used for user authentication) is not not possible to register new users via EmForge at all. To do not display "Register" link you can set this property to false;
• security.assignWriterByDefault - is configured, should registered user receive WIKI_WRITER role (allowed to edit wiki-pages) or not.

Configure EmForge to use ActiveDirectory

A little bit more complex example. Since EmForge is used Acegi Security Framework for authentication and authorization, it is possible to integrate EmForge with many external systems - one of example is ActiveDirectory (or LDAP in general).

So, to make EmForge use ActiveDirectory for authentication you need replace emforge-security.xml with file attached to this document and replace followed settings there:

1. replace LDAP_URL to your URL to ldap-server. For example: ldap://ldap.somedomain.com/
2. Replace LDAP_USER to CN of user, allowed to connect to this ldap server, for example CN=SomeUser,CN=Users,DC=somedomain,DC=com
3. Replace LDAP_PASSWORD to password for this user
4. replace SEARCH_BASE to your CN, contained all users (for example CN=Users,DC=somedomain,DC=com)
5. replace EMFORGE_GROUP to your CN, stored information about your "EmForge User" group (for example CN=EmForge User,CN=Users,DC=comdomain,DC=com)

Then you need to create 3 groups in your Active Directory:

1. EmForge User (with group-name (pre-Windows 2000) set to EMFORGEUSER: include here all users, who should have access to EmForge;
2. EmForge Admin (with group-name (pre-Windows 2000) set to EMFORGEADMIN: include here all users, who should have admin access to EmForge;
3. Wiki Writer (with group-name (pre-Windows 2000) set to WIKIWRITER: include here all users, who should be able to edit wiki-pages in EmForge;

Then ActiveDirectory or LDAP is used, and "Register" is still allowed, all users, registered via EmForge will be added into Database (emfrg_user table). EmForge allowed to mix user and group information from different sources (for example from Database and from ActiveDirectory).