Details Print

EmForgeSetupGuide

EmForge After Installation

It does not make sense how you installed EmForge - deployed EmForge.war into your J2EE server, used EmForge-launcher with bundled Jetty, or installed it with using MSI Installer - EmForge designed to be usable out-of-box after installation. So, you can start 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 file in your preferred text-editor. All these files are placed under EmForge-installation (latelly called ${root}) which is depends from how did you installed it:

• If you install it with using MSI installer - path is configured during installation - and may be changed (by default it is C:\Program Files\EmForge). IN this case ${root} will be C:\Program Files\EmForge\webapps\root
• if you used EmForge-Launcher, and placed content of archive for example into C:\EmForge - ${root} will be at C:\EmForge\webapps\root
• If you deployed EmForge.war (for example) into Tomcat - ${root} will depends from there tomcat is installed and will be ${tomcat.dir}/webapps/EmForge
• About same for other servers;

Main Configuration File you will need to work with:

• ${root}/WEB-INF/classes/config.properties - common configuration file
• ${root}/WEB-INF/classes/config-user.properties - user-specific configuration file. Initially it is not exists - so, just create it, and, instead of changing property in config.properties - write your properties here. During EmForge Upgrade, Installer will replace default config.properties (and probably add new properties into it) - but your config-users.properties will be kept. So, your configuration changes will stay between upgrades
• ${root}/WEB-INF/classes/META-INF/emforge-ds.xml - SpringFramework configuration file to setup Data-Source, used by EmForge

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

If you will have any questions - always feel free to ask in Forum - hope we will be able to answer.

Remove default admin login

First of all you will need to remove at all - or change password for admin login. To do it simple change option security.admin.password in config.properties to new value. It make sense also to change security.admin.email

If you want to assign admin role to some user, stored in Database 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 path

All links generated by EmForge UI should be generated correctly independencly from there is it installed (port, context-path). But, for correct generation of links in external documents like PDF, Reports, Email) you need to set property

application.path=http://localhost:8080/EmForge/

Configure EmForge to use another SCM Repository

By Default, EmForge is configured to use scm:svn:https://emforge.svn.sourceforge.net/svnroot/emforge repository to view in Source-Browser Tab.

If you want to change it to your own repository - simple edit linein config.properties to some SCM URL you need. For more details look into EmForge SCM Configuration

 

source.scm.url=scm:svn:https://emforge.svn.sourceforge.net/svnroot/emforge

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 EmForge 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 EmForge'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 (in most cases may be avoided, since Hibernate will autodetec required 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.

SMTP Server Configuration

To be able to send emails EmForge should be able to connect to some SMTP Server. Here is options, controller SMTP server connection:

• email.host - host name of SMTP server (localhost by default)
• email.port - port used for connection. Keep -1 to use default
• email.username - username (in cases then authentication required)
• email.password - password
• email.useSsl - set to true, in case then connection done via SSL

By default, EmForge configured to use local smtp server (available on most unix-systems), but, you can configure it (for example) to use any external SMTP server. Here is example of configuration for sending via Google SMTP:

email.host=smtp.gmail.com
email.port=-1
email.username=you_account@gmail.com
email.password=your_password
email.useSsl=true

Configure email connection via JNDI

It is also possible to use mail Session, configured on application server level via JNDI. If you already have connection configures, just put it's name into email.sessionName and leave host, username and password empty, like:

email.sessionName=mail/Session
email.host=
email.port=-1
email.username=
email.password=
email.useSsl=false

Extra email settings

There are some other properties related to emailing you can change:

• email.defaultFromAddress - email used for from-address by default (then for example registration notification email sent
• email.testMailAccount - if this property is not empty, ALL emails will be sent to this email (instead of real recipient). May be helpful for testing

 

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 OpenLDAP 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.
• security.assignWriterByDefault - is configured, should registered user receive WIKI_WRITER role (allowed to edit wiki-pages) or not.
• security.allowAnonymousAccess - true is default, allowed to anonymous access to EmForge. If you will change it to false - only regustered users will able to access EmForge.
• security.openid.enabled and security.openid.roles - responsible for OpenID authentication configuration. For more details looks on EmForge OpenId integration page

Configure EmForge to use OpenLDAP or ActiveDirectory

See Active Directory tutorial for details about configuring EmForge to use ActiveDirectory for authentication

OpenLDAP page described some details on OpenLDAP configuration (comparing to ActiveDirectory)

 

Wiki Configuration

It is possible to configure different properties related to EmForge Wiki like:

• how pages and attachments stored;
• how search-index stored;
• how PDF generated

All of them described in EmForge Wiki Configuration page

Another l10n options

Under some J2EE servers (for example JBossAS 4.2.2+) we met strange localization problems - text come from browser to server in latin1, not in UTF-8. To fix it you need to change option :

application.useUtf8Decoding=false

But - do it only in case you have problem with localization - in other cases it may produce problems, not fix it. By default, this options is false. We set it only for JBossAS. Probably, in some cases you will need to set it for your server.

User-Interface settings

It is possible to tweak ui behavior of EmForge - some properties are responsible for it:

• ui.onePageNewTask=false - switching this option to true will allow users to create new task not in step-by-step wizard (like emforge.org used) - but from one page, included ALL settings, required for task creation