Download pulse

Installing pulse in eight easy steps

A guide for the impatient.

This guide assumes you will install pulse on Apache Tomcat and MySQL using the binary release.

''
If your operating system uses a different default encoding than UTF-8 (e.g. all versions of Windows), you will have to add the following option to the Tomcat startup script to ensure the proper character encoding: -Dfile.encoding=utf-8
We also recommend to add URIEncoding="utf-8" to the <Connector/> elements in CATALINA_HOME/conf/server.xml.

Step 1: Download the current binary release

Download our current binary release directly from Sourceforge. If you are using Java 5, you will also need the Java 5 compatibility pack.

Step 2: Unzip the binary release

Unzip the binary release to a directory of your choice and examine the directories:

  • webapp: contains the pre-built pulse webapp
  • custom-webapp: is for files from webapp that you have edited
  • build: should be empty at the moment and will later contain your customised version of pulse
  • util: contains utilities needed during the installation process

Step 3: Configure logging

Enter the location where pulse shall store its log files. Copy webapp/WEB-INF/conf/log4j-config.xml to custom-webapp/WEB-INF/conf/log4j-config.xml and apply your changes. 

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" threshold="all" debug="false">
    <appender name="LOG" class="org.apache.log4j.DailyRollingFileAppender">
        <param name="File" value="../webapps/pulse/WEB-INF/log/pulse.log"/>
        <!-- For more information on using the date pattern 
        see the javadoc of DailyRollingFileAppender. -->
        <param name="DatePattern" value="'.'yyyy-MM-dd"/>
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p [%-15x] %c - %m%n"/>
        </layout>
    </appender>

    ...

</log4j:configuration>

All you have to do is changing the value of <param name="File"/> to the desired location. We recommend that you use absolute paths here.

Step 4: Enter the database settings and ports for HTTP and HTTPS

Copy the main configuration file pulse.xml from webapp/WEB-INF/conf to custom-webapp/WEB-INF/conf and edit as required by your setup. As this quick guide assumes you will be using pulse on a single server with MySQL all you have to do is change the database settings according to your installation.

If you use a Tomcat default installation, you will also have to change the security-settings: change the available attribute to true, if you have an SSL certificate installed, otherwise leave it on false.

!
If Tomcat is running on port 8080 for HTTP and 8443 for HTTPS (the defaults), you will have to change the secure and default port settings accordingly. 
<?xml version="1.0" encoding="UTF-8"?>
<configuration bean="org.torweg.pulse.service.ServletConfig">        

    ...
    
    <security tls-available="false" secure-port="443" default-port="80" 
        server-salt="changeMeOnInstall"/>
    
    ...

    <hibernate-configuration>

        ...

        <property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property>
        <property name="hibernate.connection.url"
          >jdbc:mysql://127.0.0.1:3306/pulsedb?autoReconnect=true&amp;characterEncoding=UTF-8</property>
        <property name="hibernate.connection.username">root</property>
        <property name="hibernate.connection.password">pass</property>

        ...

    </hibernate-configuration>

    ...

</configuration>

The above snippet contains the HTTP/HTTPS port settings as well as the database configuration with driver class, JDBC URL, user name and password. All other values of pulse.xml can be left alone for now.

Step 5: Setting up the database and database user

Open your MySQL console and type the following:

  • CREATE DATABASE pulsedb DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
    This will create a new database named pulsedb.
  • GRANT ALL ON pulsedb.* TO root@localhost IDENTIFIED BY 'pass';
    This will grant all privileges to the user root connecting from localhost.

You may have to substitute the username, password and database to the settings you made earlier in pulse.xml.

Step 6: Build the webapp and fire up Tomcat

Now build pulse by executing either:

  • build.bat on Windows
  • ./build.sh on Linux/Unix

This will build both an unpacked webapp and a WAR archive in the build directory.

Once the building has finished, copy the unpacked webapp from build/pulse(including the folder "pulse") into Tomcat's webapps directory.

Now start your Tomcat server and take a look at the log file, if the applications has been able to start up properly. If there have been errors, the log messages will help you to fix the problems on your system.

Hint: You have defined the location of the log file in step 3.

Step 7: Get the initial root password from the log file

If the application has been able to start, you will find the password for the auto-generated root user in the log file. 

2009-08-04 15:30:42 INFO  [startup        ] org.torweg.pulse.accesscontrol.AbstractUserBase - 
Created new superuser root identified by Szt(JRcNfE*f6P6

Look for the above line and copy the password before proceeding with the final step.

Step 8: Log in for the first time and change the root password

Log in using login.jsp. Use root as the user name and the password from the log file.

This will automatically take you to the administration interface. The first thing you should do now is changing the password for root. If you are new to pulse, you should continue reading the administation manual.