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.url, db.username, and db.password to change.
- The datastore and GeoLiteCity.dat being assumed to be under /home/fluxtream/projects: edit btdatastore.exec.location, btdatastore.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.properties, local.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 Id, App Secret, and OAuth 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
Moves
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.
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
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`