Objectives

Deploy the donation-service app to Heroku. This will require a heroku account + a locally installed git tool set.

Git Bash

This will be used in this lab. We shall refer to as Git Bash.

Figure 1: Installation Wizard Git Bash

All the following commands should be run within the Git Bash terminal, not the standard windows terminal (Command Prompt).

SSH Keys

This section applies only if you do not have SSH keys on your computer. We shall explain shortly how you can check whether or not keys are present.

Official Heroku documentation on managing SSH keys is available here

Your computer will communicate with Heroku using Secure Shell (SSH).

Here are brief instructions on how to check for the presence of SSH keys on your computer and to generate them if necessary.

Git Bash should have an SSH client. Verify this with the following command:

ssh -v

The response should be similar to this:

Figure 2: Verify presence of SSH client

Check if you already have SSH keys by checking for the presence of the.ssh folder and if it exists, listing its contents:

ls -l ~/.ssh

If keys are present then the response should be something simiar to that shown in Figure 3:

Figure 3: SSH Keys

If keys are not present then generate a set with this command:

ssh-keygen

Accept the default prompts and in particular when prompted for a password and to confirm the password simply hit the return key on both occasions but without typing any characters for the password.

That is: do not password protect the keys.

Confirm that keys have been successfully generated by checking the contents of the .ssh folder which should be similar that shown in Figure 3 above.

Local Repository

Delete the file Bootstrap.java (if it exists).
In the donation-service-play project, create a file called '.gitignore'. Here are its contents:

# Ignore all dotfiles...
.*
# except for .gitignore
!.gitignore
!.classpath
!.project


# Ignore Play! working directory #
war
db
eclipse
lib
log
logs
modules
precompiled
project/project
project/target
crud/*
data/*
conf/crud/*
conf/cloudbees*
public/crud/*
target
tmp
test-result
server.pid
*.iml
*.eml

In the same folder, create and a file named ProcFile containing the following:

web: play run --http.port=$PORT $PLAY_OPTS

Next, we need to make one significant change to the app. Open the 'Users' model and adjust the the class as follows:

@Entity
@Table(name="`User`") //This is necessary because User is a reserved word in PostGreSQL
public class User extends Model

'User' is a reserved table name in the database, so we change it to something slightly different.

In Git Bash terminal cd into the folder containing your donation-service-play project, and create a git repository for the project:

git init

Add all files (except those matched by .gitignore) to the repo and commit:

git add --all
git commit -m 'first commit'

Verify by running the command

git status

The response should as follow:

Heroku repository

Create an account on Heroku. Note carefully your login and password.

Download and install Heroku Toolbelt for Windows. Close and reopen Git Bash following installation of Toolbelt.

Once installed, verify installation ok by typing

heroku --version

The response should be something like:

heroku/toolbelt/3.12.1 (i386-mingw32) ruby/1.9.3

heroku login

You will be prompted for you email and password. Successful authentication will be confirmed.

Next create an app and repository on Heroku as follows:

heroku create

The response will be something like this:

Figure 1: Heroku: app and repository created

Notice the default name assigned by Heroku to the remote app.

Verify with the command

git remote -v

and observe a response similar to that in Figure 2.

Figure 2: Checking remote repo on Heroku

Now add your SSH keys to Heroku:

heroku keys:add

Figure 3: Heroku: Adding SSH Keys

Finally, push the local repo to Heroku:

git push heroku master

The response should be somewhat similar to that shown in Figure 4.

Figure 4: Successful deployment

We shall now test the service: In the specific case of this lab we have been randomly assigned a remote Heroku repo named guarded-reef-267.git. The convention for construction a URI to access this repo or service can easily be deduced by studying the URI for this specific service:

http://guarded-reef-2677.herokuapp.com/api/users

The portions /api/users is determined by how we, the developers, wrote the application (donation-service). Notice where the actual name of the repo is located in the URI:

- guarded-reef-2677

Copy this URI into a browser's navigation bar: unfortunately an application error is flagged. The reason for this is that we have not set up a suitable database on Heroku. We shall attend to this shortly.

Changing name of Heroku app

We shall now change the Heroku-assigned name guarded-reef-2677 to a more meaningful name org-wit-donation-service-id where id is your email address excluding @, periods, underscores and so on. For example john_doe@organs.com becomes johndoeorganscom. This is just a suggestion to ensure that the name you choose for the app on Heroku will be unique.

Run the following command within the Heroku terminal:

heroku apps:rename org-wit-donation-service-id

A typical response is shown in Figure 5:

Figure 5: Changing name of Heroku app from command line

Heroku Database

You created a Heroku app in an earlier step (using the command heroku create)

A database was made available as part of the app creation process.
You can verify this by running the following command:

heroku pg:info

A typical response is depicted in Figure 1.

Figure 1: Database information

In this case the DATABASE_URL is HEROKU_POSTGRESQL_MAUVE_URL.

Figure 2: App and associated database details on Heroku site

In order to make use of this database do the following:

Modify the application.conf file:
- Comment out any database activation statments such as, for example, db = mem.
- Add the following block to the end of the file.

#================heroku databse config config=========================
db=${DATABASE_URL}
jpa.dialect=org.hibernate.dialect.PostgreSQLDialect
jpa.ddl=update
#================end database config heroku config====================

In the Heroku terminal add and commit the changes:

git add --all
git commit -m 'database configured'
git push heroku master

The response should be similar to that shown in Figure 3. Figure 3: Application + configured database pushed to remote heroku repo

Test App

You can test that the application is working correctly in a number of ways, listed here:

Run the following command: output similar to that in Figure 4 indicates your app has been successfully deployed.

heroku ps

Figure 4: Successful deployment

Next run the command to open a browser: Figure 5 shows the command and additionally the response to the command and the output in the browser if the app is running correctly.

heroku open

Figure 5: Application ready

Finally, introduce this URI in a browser's navigation bar: the expected response is shown here in Figure 6:

http://org-wit-donation-service-id.herokuapp.com/api/users

Figure 6: List of users returned in resonse to query

Reset Database

You can reset the database as follows:

First obtain the DATABASE_URL with the following command:

heroku pg:info

A typical response is depicted in Figure 7.

Figure 7: Database information

In this case the DATABASE_URL is HEROKU_POSTGRESQL_MAUVE_URL. The command to run to reset is:

heroku pg:reset HEROKU_POSTGRESQL_MAUVE_URL

Follow the instructions as indicated in Figure 8.

Figure 8: Resetting the database

References

Deploying with Git

Remote Repository

This step is optional - and you can safely skip it for the moment.

Your app is now stored in a remote repository on heroku. You can regenerate it on another mahcine / folder if you wish:

Create a new working folder, for example workspacePlay
Change directory into this folder

cd workspacePlay

If not already logged in to Heroku, do so now:

heroku login

Obtain a clone of the remote repo:

 git clone git@heroku.com: NAME OF THE REPO HERE.git

Figure 1: Cloning heroku repository

The project will now be recreated in a folder named after the application, Change directory to this folder and run the command to allow the project to be imported into an Eclipse workspace:

play eclipsify

Launch Eclipse, switch to the workspace workspacePlay and import the project:

Figure 2: Importing project into Eclipse workspace

Note that earlier we pushed to Heroku with the following command:

git push heroku master

This will not now work. To understand why check the remote:

git remote -v

Notice that it is origin, not heroku.

Working with origin will work ok.

But perhaps it is better to preserve Heroku convention which requires that we:

Remove origin as the remote
Replace with heroku

This can easily be achieved with the following commands:

git remote remove origin
git remote add heroku git@heroku.com:org-wit-donation-service-id.git

Then, push with the following command:

git push heroku master

Exercises

Archive of donation-service as used in this lab

donation-service

Exercise 1:

Using postman, create a few Users and Donations on the app hosted in heroku. Verify that the creation/deleting proceeds as expected

Exercise 2:

You have some tests in the donation-service-test project, which currently tests the app running on localhost. Change this app such that it will test the application you have now deployed to heroku. A one line change to the Rest class should be sufficient.