Installation: Linux (original Ubuntu 10.04 instructions)

Owned by Anne Wright
Last updated: Jun 05, 2015 by Chris BartleyVersion comment
4 min read

These instructions cover installing Fluxtream, datastore, and Tomcat as of July 19, 2012 on Ubuntu 10.04 instances.  This should be sufficient to run a local instance on similar Ubuntu distributions, but does not fully work for newer distributions (problems with Maven), and does not cover running under apache.  A newer approach to server installation that works on Ubuntu 12.04 and which contains improvements graciously submitted by quantimodo are here.

Hopefully this record will at least be helpful in getting started.  If you hit rough spots, please feel free to contact us at info@fluxtream.com.

These instructions cover Linux, specifically Debian and variants thereof such as Ubuntu. For other platforms, see the corresponding installation instructions:

I arbitrarily chose to use the following paths and the notes below reflect these choices.  Feel free to make other selections and adjust the execution lines for your setup accordingly:

  • fluxtream-app and datastore are checked out into ~/projects
  • the key-value store for the datastore in ~/projects/db
  • tomcat installed in /opt/tomcat
  • downloaded packages put in ~/install

Before starting, make sure you have a working installation of mysql and that you have credentials for it.

Setup global environment

Add to /etc/bash.bashrc

export TARGET_ENV=local
export JPDA_TRANSPORT=dt_socket
export JPDA_ADDRESS=9000

Start new bash shell to get the environment variables Tomcat will need.  Double check that the variables are set:

typing echo $JPDA_ADDRESS should show 9000

Install required packages

 sudo apt-get update
 sudo apt-get install git-core
 sudo apt-get install maven2
At the end of this step, the commands should succeed:
 git --version
 mvn --version

If you use a system other than Ubuntu, you will need to figure out how to install git and maven on your own.  Please submit these back to us at info@fluxtream.com.

Get java compilation environment set up

 mkdir ~/install
 cd ~/install/

Follow instructions from http://askubuntu.com/questions/55848/how-do-i-install-oracle-java-jdk-7 for how to download Java for your system:

 tar xzvf jdk-7-linux-x64.tar.gz 
 sudo mv jdk1.7.0 /usr/lib/jvm
 sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.7.0/bin/java" 1
 sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.7.0/bin/javac" 1
 sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.7.0/bin/javaws" 1
 sudo update-alternatives --config java
  Select /usr/lib/jvm/jdk1.7.0/bin/java 

At the end of this step, the following commands should succeed:

 java -version
 javac -version

Install Tomcat and set up permissions

Download tomcat from http://tomcat.apache.org/download-70.cgi
  We saved the Binary Distributions->Core  to  ~/install/apache-tomcat-7.0.27.tar.gz
  

Unpack and set up:

 cd /opt
 sudo mkdir tomcat
 cd tomcat/
 sudo tar xvzf ~/install/apache-tomcat-7.0.27.tar.gz
 sudo ln -s apache-tomcat-7.0.27 home
 cd /opt
 sudo chown -R <appropriate owner, for Apache this may be www-data> tomcat
 sudo chmod -R g+rw tomcat
At the end of this process, tomcat should be set up. The directory we set up tomcat in will be referred to as ${TOMCAT_HOME} in the rest of the instructions. 
Bash commands to set this up are (this environment variable is not used after setup, so you do not need it in .bash_profile)
Linux:
 export TOMCAT_HOME=/opt/tomcat/home

Checkout, set up, and build the datastore

 mkdir ~/projects
 cd ~/projects
 git clone git://github.com/BodyTrack/datastore.git
 cd datastore
 make test

Create a directory for the key-value store the datastore will use.  This directory will get big, so the default location here may not be appropriate.  If you use an alternate location, make sure to modify the btdatastore.db.location property in local.properties accordingly.

 mkdir ~/projects/db
 mkdir ~/projects/db/dev.kvs

Make sure that the permissions on that directory is such that tomcat will be able to write to it.

Checkout, and set up fluxtream-app

 cd ~/projects/
 git clone git://github.com/fluxtream/fluxtream-app.git fluxtream-app 

Copy MaxMind's GeoLiteCity.dat database to ~/projects/fluxtream-app:

 cd ~/projects/fluxtream-app
 wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
 gunzip GeoLiteCity.dat.gz

Checkout, and set up scribe-java

 cd ~/projects
 git clone https://github.com/fluxtream/scribe-java.git
 cd scribe-java/
 mvn install

Setup properties files

Copy the sample properties files to their real location:

 cd ~/projects/fluxtream-app/fluxtream-web/src/main/resources/
 cp samples/*.properties .

Work through the comments in local.properties and oauth.properties to replace instances of xxx with appropriate values.  

Build the fluxtream-app project

 cd ~/projects/fluxtream-app
 mvn install

Create database and import cities1000.sql

WARNING: Since the time these instructions were written this has changed: you need to load the schema first.  Contact Anne or Candide for how.

The Running Instructions say that the database will be created automatically after running Tomcat for the first time.  In my experience this doesn't necessarily work, so I manually created the database and imported cities1000.sql before starting Tomcat.  Modify the args in the following line according to your mysql configuration.

  mysql -u root

At mysql prompt:

 create database flx;

Exit mysql (ctrl-d) and import the cities1000 table:

 mysql -u root flx < ~/projects/fluxtream-app/cities1000.sql

Setup Tomcat to point to fluxtream-app for webapps

 cd ${TOMCAT_HOME}/webapps/
 sudo mkdir ../hold
 sudo mv ROOT examples docs ../hold
 sudo ln -s ~/projects/fluxtream-app/fluxtream-web/target/ROOT

Make sure the permissions for everything Tomcat will try to get to are appropriate.   If using Apache, this would be the www-data group.  Modify below for other user configurations.

 cd /opt/tomcat/home/webapps/ROOT
 sudo chgrp -R www-data *

Start Tomcat, check logs

 cd ${TOMCAT_HOME}
 ./bin/catalina.sh start

NOTE: Follow the above directions precisely.  It won't work if you cd into the bin directory and run ./catalina.sh start from there.  Furthermore, make sure you cd to the TOMCAT_HOME directory before starting the server, rather than starting it with a command using an absolute path such as "/Library/Tomcat/Home/bin/catalina.sh start".  The Log4J configuration file references its output file (all.log) using a relative path, and it's relative to the directory you're in when you start the server.  So, normally, if you cd to TOMCAT_HOME before starting the server, the Log4J log file will be at TOMCAT_HOME/logs/all.log.  However, if you instead start the server using the absolute path command shown above while in, say, your user home directory, then the log file will be at ~/logs/all.log.

Watch the logs for startup messages:

 tail -f ${TOMCAT_HOME}/logs/catalina.out

When this is done the log will say something like:

 INFO: Server startup in xxx ms

Test that Tomcat is working

Browse to http://localhost:8080

This should bring up the fluxtream login screen, as you would see at https://sandbox.fluxtream.com

Register for an account (http://localhost:8080/register), try things out, it should all be good.

Next steps

Instructions on setting up an HTTP server such as Apache to talk to tomcat is outside the scope of this page.  There is an example of one way to do it in the Amazon EC2 setup example in case it helps.

We have open source licenses for JRebel and IntelliJ IDEA which have the potential to greatly improve the developer experience.  Docs for that part of the setup are not done yet, though there is a start on that effort at Development and debugging with JRebel and IntelliJ IDEA.  

Please contact us at info@fluxtream.com if you would like further assistance on those fronts.