jpa02 : Spring Boot and Heroku Hello World

num ready? description assigned MW lect due MW lect assigned TR lect due TR lect
jpa02 true Spring Boot and Heroku Hello World Tue 04/05 02:00PM Mon 04/11 11:59PM

Individual lab, but you may help one another

This is an individual lab on the topic of Java web apps on Heroku.

You may cooperate with one or more pair partners from your team to help in debugging and understanding the lab, but each person should complete the lab separately for themselves.

Ask for help on #help-jpa02

There should be a slack channel called #help-jpa02 where you can ask questions about this assignment. Check that channel first to see if your question has already been answered.

Step 1: Understanding what we are trying to do

What are we trying to accomplish again in this lab?

Why use Heroku?

Limitations of the free plan of Heroku

TL;DR: You should NOT need to enter a credit card into Heroku. If you are asked for one, something has gone wrong.

Web Apps vs. Static Web Pages

You may already have some experience with creating static web pages, and/or with creating web applications (e.g. using PHP, Python (Django or Flask) or Ruby on Rails.) If so, then the “Learn More” section will be basic review.

If you are new to writing software for the web, you are strongly encouaged to read the background information at the “learn more” link below.

What are we trying to accomplish again in this lab?

If you just did a deep dive into the article Web Pages vs. Web Apps it may be helpful to again review what we are trying to accomplish in this lab:

Disk Quota

IMPORTANT: if you are working on CSIL, and at some point things just “stop working”:

Then you probably have a disk quota problem.

Step 2: Create a Heroku Account

If you do not already have a Heroku account, navigate to https://www.heroku.com/ and click the “Sign up for Free” link.

You’ll be asked for:

Step 2a: Set up Multi-Factor Authentication for Heroku

On February 1, 2022, Heroku will start requiring every user to enable Multi-Factor Authentication. This adds an additional layer of security to your account by requiring access to something physical (like a phone or a physical security key) to complete a login along with your password.

You should already be familiar with multi-factor authentication as we use Duo here at UCSB.

You can set up multi-factor authentication here. You can also get to this page by logging into Heroku Dashboard, clicking on your profile picture, then “Account Settings”, and then “Manage Multi-Factor Authentication”.

The easiest method to set up is the “One-Time Password Generator”. Clicking on the “Add” button within this option will present you with a QR code that you can scan using an authenticator app.

Finish setup by entering the code from your authenticator app into Heroku’s website.

In addition to using one-time passwords (OTPs), you can use on-device biometric sensors (such as Windows Hello, Touch ID, and Face ID) via the “Built-in Authenticators” option, or a physical U2F security key.

Note that this new requirement breaks the ability to login to Heroku by typing your credentials directly into Heroku CLI. Heroku CLI logins (i.e. heroku login) must now be completed via the browser login flow. If you are logging in from a device without a browser (such as an SSH session into CSIL), you will have to manually paste the link generated in the CLI into a web browser to complete the login.

More info on this change can be found here.

Step 3: Create your repo

You should already have a repo under the course organization ucsb-cs156-s22 called jpa02-githubid created for you by the staff, where github is your github id.

If not, create one for yourself following that naming convention; it should initially be private, and empty (no README, license or .gitignore.)

Clone that repo somewhere and cd into it.

Then add this remote:

git remote add starter https://github.com/ucsb-cs156-s22/STARTER-jpa02

Then do:

git checkout -b main
git pull starter main
git push origin main

Step 4: Start your webapp on localhost

The application should be ready to go out of the box; it starts up a web server that brings up a page with the message Greetings from Spring Boot!

We are going to run a command to start up this web server and then try to connect with a browser.

Connecting with a browser

Now, if you are running on your own machine, connecting with a browser is quite simple; the web server is running on the local machine (localhost) on port 8080, so putting the address http://localhost:8080 in your browser will just work. If you are successful, you should see the message Greetings from Spring Boot appear in your browser.

It’s the case where you are running on CSIL where things can get more complicated.

First, there’s the possibility that port 8080 may already be taken; in that case you’ll see the error:

Web server failed to start. Port 8080 was already in use.

To see how to fix the Port 8080 was already in use error, click the triangle:

In this case, the fix is to choose another port number. Any number between 8080 and 65535 is fair game; to try another port number, use the command shown below (change 12345 to whatever port number you like):

PORT=12345 mvn spring-boot:run

You’ll need to substitute this number (e.g. 12345) in place of 8080 when trying to load the website.

To see strategies for bringing up a web page for a web server running on CSIL, click the triangle.

Strategy 1: Point browser directly at CSIL machine

If you are running on CSIL, you can try to point your web browser at the machine where the server is running instead of localhost.

For example, if you are running on CSIL and type in hostname, and see this:

[pconrad@csilvm-01 ~]$ hostname
csilvm-01.cs.ucsb.edu
[pconrad@csilvm-01 ~]$

Then substitute that name in place of localhost, e.g. point your browser as http://csilvm-01.cs.ucsb.edu:8080 instead of http://localhost:8080

This may not always work, because firewalls may prevent access. Using the UCSB VPN may help.

Strategy 2: Port Forwarding

If you are using ssh to connect to CSIL, the solution shown here allows you to forward traffic on localhost:8080 on your own machine to localhost:8080 on the machine you are connecting to:

Strategy 3: Remote Desktop

Using the Remote Desktop (RDP) Solution described in the articles below, you can load a complete “desktop” of a CSIL Linux environment and show it in a window on your Mac or Windows machine.

In the RDP window, you can open both a terminal window and a browser that are both running on CSIL. Since that browser is running on the same system as the web server, you can just use http://localhost:8080 to connect to the server.

About localhost and “Port Numbers”

The code in this repo is configured to start up a webserver on port 8080, running on localhost, which is a name for the machine on which the code is running.

So the web address to acccess your server is: http://localhost:8080.

Step 5: Undertstanding localhost vs. Heroku

When running on localhost:

Running on localhost is fine for testing and development. But eventually we want to know how to deploy a web application so that anyone on the internet can access it.

To get the web app running on the public internet, we’ll need to use a cloud-computing platform such as Heroku. Heroku allows us to deploy web applications in Java rather easily.

A side note: though we won’t explore it in this course, Heroku also makes it easy to deploy webapps in a variety of langauges, including Python, Node (JavaScript), and Ruby just to name a few. Many of the skills you’ll learn in this course about Heroku will transfer to those other languages if you want to work with them in other courses such as CMPSC 48, CMPSC 189A/B, or personal projects.)

A note about security: Let’s say up front that this is a risky thing to do. You need to be very careful about security when deploying web applications to the public internet. Fortunately, this particular application is rather simple and low-risk. We’ll discuss web security throughout the course.

Step 6: Create a new Heroku App using the Heroku CLI

In this step, we’ll deploy our Spring Boot application to the public internet using Heroku.

Use this command to login to Heroku at the command line:

heroku login

Then, use this command to create a new web app running on heroku. Substitute in your UCSBNetId (i.e. your ucsb email without the @ucsb.edu part.

That is, if your email is cgaucho@ucsb.edu, please make your heroku application name jpa02-cgaucho. This name is important, because the Gradescope autograder willbe looking for a Heroku application that matches this naming convention. If there is a reason that you cannot use this naming convention (e.g. your ucsbNetId is not accepted as part of a heroku application name because of special characters, upper case characters, etc.), please note this on the #help-jpa02 channel on Slack.

Note that you should convert your ucsbnetid to all lowercase; heroku web-app names do not permit uppercase letters, and use - in place of underscores or periods.

heroku create jpa02-ucsbnetid

Notes:

Step 7: Login to the Heroku Dashboard

Login to https://dashboard.heroku.com/apps and look for the jpa02-cgaucho app (or whatever your name is) that you created.

You should find a place where you can connect your App to Github.

Click on this, and select your repo to connect the Github Repo to Heroku.

Then, click on “deploy branch”.

What if it doesn’t work?

If it doesn’t work, try these things before asking a mentor, TA, or instructor for help.

  1. Make sure you are logged into Heroku at CLI with heroku login. If you are working on CSIL, exited your CSIL shell (logged out), and logged back in again, you have to login to Heroku again. Then repeat the commands.
  2. Try heroku logs --app appname (substitute the name of your app where you see appname). You’ll see the log output of that app on Heroku.
    • You may find it helpful to open a second Terminal, login to CSIL and the Heroku CLI, and use heroku logs --app appname --tail, which keeps the log output running continously.
    • You can also see your logs in a web browser at: https://dashboard.heroku.com/apps/app-name/logs (note that you need to put your app-name in the URL instead of app-name.
    • You can navigate to this from https://dashboard.heroku.com/ by selecting your app, clicking on it, selecting the More menu at upper right, and the selecting Logs.

Step 8: Changing what is shown on the page

Go into the Java source code under src and locate the file /src/main/java/edu/ucsb/cs156/spring/hello/HelloController.java

In this file, locate the line of code that says:

    @RequestMapping("/")
    public String index() {
        return "Greetings from Spring Boot!";
    }

This method returns the contents of the home page ("/") for the webapp.

Change that code by changing “Spring Boot” to your email address (without the @ucsb.edu part).

For example, if your email is cgaucho@ucsb.edu, instead of:

        return "Greetings from Spring Boot!";

You’ll have:

        return "Greetings from cgaucho!";

If your email contains upper-case letters, underscore (_) or periods (.) click the triangle for special instructions:

Update: The autograder has been modified to handle the cases of:

  • mixed case (upper and lowercase letters) in email addresses
  • underscores _ in email addresses
  • periods . in email addresses

In order to convert each of these to legal Heroku app names, the autograder converts your email by:

  • stripping off the @ and everything after the @
  • converting to all lowercase
  • converting _ and . to - Examples:
  • Foo.Bar@ucsb.edu becomes foo-bar
  • My-Lit.tle_pony@umail.ucsb.edu becomes my-lit-tle-pony

So, if your email address is My-Lit.tle_pony@umail.ucsb.edu, you should modify your code to replace:

        return "Greetings from Spring Boot!";

with

        return "Greetings from my-lit-tle-pony!";

If your email presents any other corner cases that are handled above, make a post on #help-jpa02 on slack to ask for help.

Then:

If it works, then the words “this github repo” should become clickable links.

Ok, so far, we haven’t really done anything we couldn’t have done with a static web page. But we have gotten a working Java web app running on Heroku, so it’s start we can build on.

Step 9: The test cases

You’ll see that when you run “mvn test” that there are test cases, some of which are now failing.

The test cases are in these files:

Run the tests and see them fail.

Then modify them so that they pass. Note that we are doing TDD “wrong” this time; to do it “the right way”, we should have modified the tests first, and then modified the code so that the tests pass. We’ll pivot to this style of working once we have a better grasp on all the moving parts here.

Step 10: Adding links to repo in the README.md

Edit your README.md. You’ll find some TODO items inside indicating what edits you need to make.

All quarter long, we want you to develop the habit of adjusting the README.md in your repo to include a link to your repo.

The link to your repo may seem redundant, but it helps your mentors, TAs and instructors; when you submit your work for grading to either Gradescope or Gauchospace, having those links handy really helps us navigate through your assignments quickly to evaluate them and assign grades.

Step 11: Submitting your work for grading

When you have a running web app, make a submission under jpa02 on Gradescope.