Setup and Maintenance of Fluxtream Server Instances

Setup properties files

As mentioned in the setup instructions, when initially setting up a Fluxtream server instance you should copy the sample properties files to their real location and edit them:

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

Edit the values in local.properties to customize your Fluxtream install to match your situation.  If you leave the default values alone you will end up with:

  • A mysql port of 3306, username of flx with mysql password fluxtream: edit db.urldb.username, and db.password to change.
  • The datastore and GeoLiteCity.dat being assumed to be under /home/fluxtream/projects: edit btdatastore.exec.locationbtdatastore.db.location, and geoIpDb.location to change.
  • The URL assumed for running your local Tomcat dev instance of http://localhost:8080/: edit homeBaseUrl to change.
  • A white-label welcome page: edit homepage.name to change.  If you set the value of homepage.name to foo, the Fluxtream server will look for the file fluxtream-web/src/main/webapp/WEB-INF/jsp/foo.jsp. 
  • A default location of Pittsburgh (only affects running on a local dev instance): edit defaultLocation.latitude and defaultLocation.longitude to change.

Edit the crypto key in common.properties to some long and hard to guess phrase.  If left at the default value you will end up with a pitiful encryption key for encrypting the values in the ApiKeyAttribute table.  IMPORTANT: if you ever change or misplace the value of this key used when populating the attributes in a given ApiKeyAttribute table you will lose the ability to update any of the user's connectors in that instance.  If you copy a Fluxtream DB from one server to another, be sure to set up the crypto key with the same value, or else clear out all the connector-related tables.

Many services require keys which we cannot in general distribute and which must be set up individually for each server instance.  The places in common.propertieslocal.properties and oauth.properties where these parameters need to be set default to having the value xxx.

If you don't wish to use a given service, leaving the xxx values in place will let the Fluxtream server know that you intentionally do not wish to use that service and it will try to cope without undue complaint.  

If a key is missing entirely, which may happen in the case of new keys being added after your initial setup, the server will complain and may refuse to start up.

In the case of connectors which use oauth, the server will check for the existence of the appropriate keys in the properties file and disable the connector if the keys are either not present or set to xxx.  

For example, the key names in the properties file for the BodyMedia connector are bodymediaConsumerKey and bodymediaConsumerSecret.  If those keys are present and not set to xxx, the entry in the Connector table for the bodymedia connector will be set to enabled=Y and BodyMedia will appear in the Add Connectors dialog.  If those keys are either absent or set to xxx, the Connectors table will be set to enabled=N and BodyMedia will not appear in the Add Connectors dialog.

Details on the various services are discussed below.  The properties keys themselves are listed in heavy italics.

Need to be set up special for each server

The following services tie OAuth keys to a particular redirect URL and so must be set up with a different key for each server and each port you want to use.  This also means that a given server instance can only add these connectors when accessed in one particular fashion.  For instance, if a given server instance can be accessed via more than one URL root (such as http://foo.com and https://foo.com), it only works to add the connector when the user has accessed the site via the canonical route submitted when you generated the OAuth key.

Jawbone

if jawboneUp.client.id, jawboneUp.client.secret, and jawboneUp.validRedirectURL are set to a non xxx value in oauth.properties, Fluxtream can support the use of Jawbone UP connectors.  If any are not set, Jawbone will not be available via the add connector dialog.  

The Jawbone developer site is here.  To request an OAuth key from Jawbone, you will need to log into your Jawbone user acount, then click on Account/Create an account along the left side menu of the Jawbone developer site.  You can create a Jawbone user account by either going to https://jawbone.com/user/login, or via the Jawbone UP cell phone app when you run it for the first time. 

The Create an account item will bring you to a form to create an "Organization", including a name description and logo.  These are what the user will see on the OAuth2 authentication page when doing the OAuth dance to connect or reconnect to their Jawbone account later on.  Click on the "Create Vendor" button.  Once you have done this once, you can create an application belonging to that organization.  

When creating an application, fill in the fields with appropriate URLs for your project.  In the section for OAuth Redirect URIs, put https://<your server name>/up/swapToken (note that the choice of http: vs https: matters and should match your setup).  For local testing, this would be http://localhost:8080/up/swapToken.  Leave the Pub/Sub section disabled unless you have added specific support for it.  A Fluxtream instance built from sources won't need it, and you couldn't use it for testing on a dev instance anyway (localhost:8080 isn't an externally routable address).

After completing app registration, you will see the name you registered along the bottom of the left side menu of the Jawbone developer site under Applications.

When you're looking at your Jawbone Application, either because you just created it or because you clicked on a previously created one, you will see values for Client IdApp Secret, anOAuth redirect URLs.  These are the values you'll need to copy into  jawboneUp.client.id, jawboneUp.client.secret, and jawboneUp.validRedirectURL in oauth.properties.  You can have multiple OAuth redirect URLs associated with a given Jawbone application.  Just copy the one that's appropriate for a given Fluxtream instance into oauth.properties.  

Once you have set up the keys, rebuild, rerun, and check that Jawbone UP now appears when you do Add connectors.

Flickr

If flickrConsumerKey, flickrConsumerSecret, and flickr.validRedirectURL are set to a non xxx value in oauth.properties, Fluxtream can support the use of Flickr connectors.  If any are not set, Flickr will not be available via the add connector dialog.  
To request an OAuth key from Flickr, log into your Flickr account and then browse to http://www.flickr.com/services/apps/create/apply/ and follow the directions.  When asked to supply a Callback URL, use:
<your server root>/flickr/upgradeToken
 
For example, for running Tomcat locally on port 8080 you would use http://localhost:8080/flickr/upgradeToken.
Set the flickr.validRedirectURL in oauth.properties to the same value you submitted for the Callback URL, and set flickrConsumerKey to the Key and flickrConsumerSecret to the Secret value Flickr gives you for the key request.
If you have already created an app and want to manage your keys or add keys for new server instances, go to http://www.flickr.com/services/apps/by and either select the key you want to edit, or click the Get Another Key button in the upper right.

Once you have set up the keys, rebuild, rerun, and check that Flickr now appears when you do Add connectors.

Moves

If moves.client.id, moves.client.secret, moves.validRedirectURL, foursquare.client.id, and foursquare.client.secret are set to a non xxx value in oauth.properties, Fluxtream can support the use of Moves connectors.  If any are not set, Moves will not be available via the add connector dialog.  
To request an OAuth key from Moves, go to https://dev.moves-app.com/apps/new and follow the directions.  It will prompt you to log into your google account, and management of this set of Moves keys will be tied to the google account used at this time.  When asked to supply a Redirect URI, use:
<your server root>/moves/oauth2/swapToken
 
For example, for running Tomcat locally on port 8080 you would use http://localhost:8080/moves/oauth2/swapToken.
Set the moves.validRedirectURL in oauth.properties to the same value you submitted for the Redirect URI, set moves.client.id to the Client ID and moves.client.secret to the Client Secret value Moves gives you for the key request.
If you have already created an app and want to manage your keys or add keys for new server instances, go to https://dev.moves-app.com/clients and either select the key you want to edit, or click the Register a New API Client button in the upper right.

You will also need to get foursquare keys in order to retrieve the icons used by moves.  The properties for this are foursquare.client.id and foursquare.client.secret.  I have not personally gone through the process of applying for these, so a writeup of the process will need to await further developments.  If you do this successfully please let me know at info@fluxtream.org.  If you try but need help, also email that address and I can work with you to figure it out.  

Once you have set up the keys, rebuild, rerun, and check that Moves now appears when you do Add connectors.

Can use same key for multiple servers

Postmark

If postmarkApiKey set to a non xxx value, Fluxtream can use the Postmark service to send password reset emails to users.  If it is not set, the password reset email feature will not work.  

You wil also need to set up postmarkSendAddress to be the address used in the from field of the email.  This must match the account set up in postmark corresponding to the postmarkApiKey.

Postmark is not free, but (at least as of June 2013) they offer a trial period where the first 10,000 emails free.  You can sign up for an account here.  

World Weather Online

If wwo.key and wwo.feedkey are set to a non xxx value, Fluxtream will be able to retrieve weather stats for users.  

This feature requires the World Weather Online Premium API which is not free, but (at least as of June 2013) they offer a one month trial period.  

Once you have set up the keys, rebuild, and rerun.  Weather information should now appear in the top navigation area below the city name for the day-level calendar view, as well as in the pop-up dialogs in the clock when a particular item is selected.

Withings

If withingsConsumerKey and withingsConsumerSecret are set to a non xxx value in oauth.properties, Fluxtream can support the use of Withings connectors.  If any are not set, Withings will not be available via the add connector dialog.  

To request a Withings developer key, go to https://oauth.withings.com, log in with your normal Withings account credentials (you can an account for free if you don't already have one).  By default it appears to go to the Register an Application page if you haven't already registered an application for that account, or the application Dashboard if you do already have one.  Note that you can only register one application per Withings account.  
Fill in the form.  Don't worry about setting Callback URL to anything special; we always override with the oauth_callback argument so the default here is not used.  Accept the Default Access type of read-only.  Once it's filled in, click "Register application".
The next page will show values for API Key, which you should copy into withingsConsumerKey in oauth.properties, and API Secret, which you should copy into withingsConsumerSecret in oauth.properties.
Once you have set up the keys, rebuild, rerun, and check that Withings now appears when you do Add connectors.

IP to Location

ip2location.apiKey

Need to know what this is for.

Google API

googleConsumerKey, googleConsumerSecret, google_latitudeApiKey.  Not sure how to set this.

 

LastFM

lastfmConsumerKey, lastfmConsumerSecret

Twitter

BodyMedia

Setup swagger-ui to server the REST API documentation

Note: you will need node.js for this

in a Terminal: `clone git@github.com:fluxtream/swagger-ui.git`

`cd swagger-ui`

`npm run-script build`

`cd $TOMCAT_ROOT/webapps`

`ln -s ~/projects/swagger-ui/dist swagger-ui`