Getting Started Guide
This guide will help you install, setup and run an Apollo broker and validate that the broker is operating correctly.
Installation
Download the Apollo distribution that is most appropriate for your operating system.
Extract the distribution archive:
Unix/Linux/OS X
tar -zxvf apache-apollo-1.0-beta1-unix-distro.tar.gz
Windows
jar -xvf apache-apollo-1.0-beta1-windows-distro.zip
Set your shell's
APOLLO_HOME
environment variable to where the extractedapache-apollo-1.0-beta1
directory is located.Add the extracted
apache-apollo-1.0-beta1/bin
directory to your shell'sPATH
environment variable.
Install the BDB library
Apollo's most robust message store implementation is the BDB based message store.
Unfortunately, BDB cannot be redistributed by Apache. It is highly recommended
that you add it to your apollo installation. You can download it from Oracle at
je-4.1.6.jar and
then copy it into the ${APOLLO_HOME}/lib
directory.
For those of you with curl installed, you can just run:
curl http://download.oracle.com/maven/com/sleepycat/je/4.1.6/je-4.1.6.jar > ${APOLLO_HOME}/lib/je-4.1.6.jar
Creating a Broker Instance
A broker instance is the directory containing all the configuration and runtime data such as logs and data files associated with a broker process. It is recommended that you do not create the instance directory under the directory where the Apollo distribution is installed.
On unix systems, it is a common convention to store this kind of runtime data under
the /var/lib
directory. For example, to create an instance at '/var/lib/mybroker', run:
cd /var/lib
apollo create mybroker
A broker instance directory will contain the following sub directories:
bin
: holds execution scripts associated with this instance.etc
; hold the instance configuration filesdata
: holds the data files used for storing persistent messageslog
: holds rotating log filestmp
: holds temporary files that are safe to delete between broker runs
At this point you may want to adjust the default configuration located in etc directory.
Updating the Configuration to use BDB
The default configuration used a jdbm2 based store. It has known performance issues so
it is recommend you change the configuration to use the BDB store instead. To do that,
just update the generated configuration by editing the etc/apollo.xml
file and then
replace jdbm2_store
with bdb_store
Running a Broker Instance
Assuming you created the broker instance under /var/lib/mybroker
all you need
to do start running the broker instance is execute:
/var/lib/mybroker/bin/apollo-broker run
Verification
You can use the ruby examples included in the distribution to verify that the broker is operating correctly.
If you have not already done so, install the stomp
Ruby gem.
gem install stomp
Change to the examples/ruby
directory that was included in the Apollo
distribution. Then in a terminal window, run:
Unix/Linux/OS X
cd ${APOLLO_HOME}/examples/ruby
ruby listener.rb
Windows
cd %APOLLO_HOME%\examples\ruby
ruby listener.rb
Then in a separate terminal window, run:
Unix/Linux/OS X
cd ${APOLLO_HOME}/examples/ruby
ruby publisher.rb
Windows
cd %APOLLO_HOME%\examples\ruby
ruby publisher.rb
If everything is working well, the publisher should produce output similar to:
Sent 1000 messages
Sent 1000 messages
...
The consumer's output should look like:
Received 1000 messages.
Received 2000 messages.
...
Web Administration
Apollo provides a simple web interface to monitor the status of the broker. Once the admin interface will be accessible at:
The default login id and password is admin
and password
.