Installing WattDepot Server On Heroku
WattDepot: A system for collecting and storing data from
electricity meters for smart grid research and experimentation.
These instructions no longer work properly due to changes at Heroku and in WattDepot. For now, they are provided as a starting point for technically-knowledgable individuals that want to get WattDepot working on Heroku.
This document explains how to install the WattDepot server as a Heroku cloud application. Following these instructions will actually result in two Heroku apps: one testing app and one production app. The testing app is optional, but highly recommended. Many of the commands below are duplicated in order to set up both apps.
- Create a Heroku account
- Install Heroku toolbelt
- Install JDK 1.5 or above (for testing)
- Install Maven 3 (for testing)
Follow Steps 1-3 of the Heroku Cheat Sheet This involves:
- Signing up with the Heroku service
- Install the Heroku Toolbelt (provides the "git" and "heroku" commands).
- Logging in to Heroku.
Note that nothing in these steps actually creates charges, but does require the account to be verified.
- Sign into Heroku and go to "My Account"
- Press the "Verify" button in the Billing Info section
- Enter the billing information to associate with this account
Open the command line and execute the following command to create your testing application:
heroku create --stack cedar
A name is given to the app, which will be part of the URL. The app name will be used in the following commands. We'll refer to it here as TESTAPPNAME, and your test app URL will be TESTAPPNAME.herokuapp.com by default. If you would like to change your TESTAPPNAME you can do so through your online Heroku account, but keep in mind that no two apps can share the same name so pick something unique (for example, "test-wattdepot-hpu").
To create the production app, run the same command:
heroku create --stack cedar
You will be given another name, which we will call APPNAME. Again, this can be changed through your online Heroku account (for example, "wattdepot-hpu").
Add an add-on shared database:
heroku addons:add heroku-shared-postgresql --app TESTAPPNAME
heroku addons:add heroku-shared-postgresql --app APPNAME
This will tell you the names of your shared databases. For example, HEROKU_SHARED_POSTGRESQL_BLACK. You need these in the next step. Let's refer to them as TESTDBNAME and DBNAME.
heroku pg:promote TESTDBNAME --app TESTAPPNAME
heroku pg:promote DBNAME --app APPNAME
A few configuration variables are required to run WattDepot on Heroku.
- wattdepot-server.hostname should be set to the URL of your Heroku application. By default, this is TESTAPPNAME.herokuapp.com or APPNAME.herokuapp.com
- wattdepot-server.heroku must be set to true
- wattdepot-server.admin.email will be the username for your WattDepot administrator
- wattdepot-server.admin.password will be the password for your WattDepot administrator.
- wattdepot-server.context.root will be the root of your app. For example, if set to "wattdepot" you will access your application via appname.herokuapp.com/wattdepot/. This value can be the same for both the test and production apps.
Determine the correct value for each variable and set them via command line:
heroku config:add wattdepot-server.hostname=TESTAPPNAME.herokuapp.com [email protected] wattdepot-server.admin.password=myPassw0rd wattdepot-server.context.root=wattdepot wattdepot-server.heroku=true --app TESTAPPNAME
heroku config:add wattdepot-server.hostname=APPNAME.herokuapp.com wattdepot-server.admin.email=[email protected] wattdepot-server.admin.password=myPassw0rd wattdepot-server.context.root=wattdepot wattdepot-server.heroku=true --app APPNAME
This step can be redone if you want to change the variables later, but it requires restarting the Heroku app.
- From the command line, change into the directory you want the code in.
cd WattDepot
- Get the code from the repository.
git clone https://code.google.com/p/wattdepot/
- Add a git remote to each of your Heroku apps:
git remote add testheroku [email protected]:TESTAPPNAME.git
git remote add heroku [email protected]:APPNAME.git
- Download and Install Maven 3 following the instructions here
- Execute the verify task to test the code
mvn verify
- The tests should take about ten minutes to complete. If there are any errors, they need to be
fixed before continuing. Check with the WattDepot developers via the Google Group to determine the
problem.
- Go to VersionHistory to find the tag of the release you want to install (for example, v1.6.130). Push the release to the test app using the tag name. Remember the tag name that you select, as you will need it again for the production app.
git push testheroku v1.6.130
- Enter authentication if requested
- Heroku will check the files to make sure it can run them. If this does not pass, Heroku won't
accept the files. Check with the WattDepot developers via the Google Group to determine the problem.
- In order to test on Heroku, we need to get the Database URL of the test app.
heroku config --app TESTAPPNAME
- Find and copy the value listed after DATABASE_URL. Paste it into another application (like
Notepad or Word) and append `?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory` to the
end of it. We'll call this the *DBURL* It should look something like this:
`postgres://zqgwamfnsv:[email protected]/evening_rain_158?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory`
- Run the test, passing in the parameters as shown below (including the quotation marks).
mvn test "-Dwattdepot-server.test.heroku=true" "-Dwattdepot-server.heroku.hostname=TESTAPPNAME.herokuapp.com" "-Dwattdepot-server.heroku.db.url=DBURL"
- The test may take around half an hour to run, since it is doing a great deal of work over the
network.
- At the end, make sure it says SUCCESSFUL. If not, there is something wrong with either the code
or the Heroku configuration. Only proceed to the next step after the tests pass.
- You can visit the app at *TESTAPNAME*.herokuapp.com
- If it says "Not Found" that means the server is running.
- If it says "Application Error", check the log files to see what went wrong
heroku logs --app TESTAPPNAME
- Push the code to Heroku, using the same tag name you used for the test app above.
git push heroku v1.6.130
- Enter authentication if requested
- Heroku will check the files again. At this point everything should be working since we already checked it.
- Visit APPNAME.herokuapp.com
- It should say "Not Found", meaning that the server is running.