Login | Register
My pages Projects Community openCollabNet

How to Install SubEtha

Note: These are the full instructions for installing from scratch. For an easier method, see the Ready To Run documentation.

These instructions describe setting up a single, standalone instance of SubEtha. If you wish to run a cluster you should consult a JBoss expert. You should have have installed JDK 1.5 and whatever database you intend to use.

  1. Install JBoss 4.0.5.GA using the JEMS 1.2.0GA installer (not the zip download!).

    1. Choose the ejb3-nonclustered option.
    2. Leave the configuration name as 'default'.
    3. Do not enable isolation/call-by-value.
    4. Secure all of the JMX access points. Be sure to use a non-guessable password.

    The remaining documentation referrs to the directory in which you installed JBoss as ${jboss.dir}.

  2. Edit ${jboss.dir}/server/default/deploy/ejb3-entity-cache-service.xml and change this line to LOCAL:

    <attribute name="CacheMode">LOCAL</attribute>
  3. SubEtha uses JavaMail to send messages through an existing Mail Transport Agent such as Postfix or Sendmail. Edit the configuration in ${jboss.dir}/server/default/deploy/mail-service.xml and set the following parameters:

    • mail.smtp.host - the name of your outgoing smtp mail server (probably "localhost")
    • mail.smtp.port - the port number of your outgoing smtp mail server (probably 25)

    You will need to add the mail.smtp.port line if you wish to change from the default (25). Everything else in the file can be left as-is.

  4. Set up the JDBC data source.

    1. Copy an appropriate JDBC driver for your database into ${jboss.dir}/server/default/lib. (Download MySQL JDBC driver (MySQL Connector/J) from here.)
    2. Configure two data sources appropriate to your particular database by copying one of the templates in ${jboss.dir}/docs/examples/jca/ into ${jboss.dir}/server/default/deploy/. There are examples for most modern RDBMSes. You can declare both data sources in the same file. The names of the data sources must be SubEthaDS and SubEthaQueueDS. Here is an example:
      <datasources>
        <local-tx-datasource>
          <jndi-name>SubEthaDS</jndi-name>
          <connection-url>jdbc:mysql://localhost:3306/subetha</connection-url>
          <driver-class>com.mysql.jdbc.Driver</driver-class>
          <user-name>root</user-name>
          <password></password>
          <exception-sorter-class-name>
          	org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
          </exception-sorter-class-name>
        </local-tx-datasource>
        
        <local-tx-datasource>
          <jndi-name>SubEthaQueueDS</jndi-name>
          <connection-url>jdbc:mysql://localhost:3306/subetha-q</connection-url>
          <driver-class>com.mysql.jdbc.Driver</driver-class>
          <user-name>root</user-name>
          <password></password>
          <exception-sorter-class-name>
          	org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
          </exception-sorter-class-name>
        </local-tx-datasource>
      </datasources>
      
      The filename is arbitrary but it should end with -ds.xml.
    3. Create the schemas (not the tables) that you referenced in your -ds.xml file. In the above example, you should create databases named "subetha" and "subetha-q"
    4. Note that JBoss will create the database tables for you when SubEtha runs for the first time.
  5. Copy subetha.ear to ${jboss.dir}/server/default/deploy/.

  6. Configure the startup scripts. You probably want to add -Dfile.encoding=UTF-8 to the JAVA_OPTS environment variable (check ${jboss.dir}/bin/run.sh or run.bat). If you are using Linux, example scripts suitable for /etc/init.d are located in ${jboss.dir}/bin/. They will require some customization for your environment.

Integrate with your MTA

Read the integration guide.

Startup

Start up JBoss by running ${jboss.dir}/bin/run.sh or run.bat. The default web interface is http://localhost:8080/se/. When SubEtha runs for the first time, it creates a site administrator account named "root@localhost", with the password "password".

Change the administrator password immediately. This can be done from the web interface.

You are now ready to continue with the Administration Guide.