jpa02 : Spring Boot and Heroku Hello World

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.

Step 0: If you are working on your own machine

If you are working on CSIL, you can skip this step.

But if you are working on your own machine, you’ll need to install a few things before proceeding.

• Java 11
• Maven
• git
• Heroku CLI

See guides for installing these on your machine at the links shown:

• Windows: https://ucsb-cs156.github.io/topics/windows/
• MacOS: https://ucsb-cs156.github.io/topics/macos/

Step 1: Understanding what we are trying to do

What are we trying to accomplish again in this lab?

• In this lab, we will create a basic “Hello, World” type web app in Java”
• A web app is a piece of Java code that takes HTTP request messages as input, and responds with HTTP response objects as output.
• Heroku is a platform where we can host a Java web app.

Why use Heroku?

• Web applications run on the “server” side of the web architecture, not the client side.
• So to test a web application, we need to set up a web server that can run Java code.
• Configuring a web server for Java is challenging. But, fortunately, we don’t have to.
• Heroku.com offers “platform as a service” cloud computing for Java web applications.
• We’ll use the “free plan” that they offer for folks just getting started with learning Heroku.
• This puts your application “on the web”, for real, so that anyone in the world can access it 24/7

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.

• If no-one has accessed your web app for a while, it “goes to sleep”, so to speak.
  • The first time someone tries to access it after it has gone to sleep, there is a noticable delay in the response, perhaps several seconds or even up to a minute.
• If too many people try to access your service per hour, eventually, you’ll run out of “free resources”.
  • That is very unlikely to happen unless you make a web app that somehow attracts the attention of a very large audience.
  • I suggest you try to avoid doing that with the web apps you develop for this class.
  • I suggest you avoid doing that in general, unless/until you have some plan for how to make money off your web app to pay for the server resources. (With a credit card, you can set up Heroku to have higher usage limits, and to keep your app running so that response time is fast. But you should NOT need that for this course.)

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.

• Web Pages vs. Web Apps

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:

• In this lab, we will create a basic “Hello, World” type web app in Java”
• To test that, we need to run that on a server somewhere.
• Configuring a web server for Java is challenging. But, fortunately, we don’t have to.
• Heroku.com offers “platform as a service” cloud computing for Java web applications.
  • We’ll use the “free plan” that they offer for folks just getting started with learning Heroku.
  • This puts your application “on the web”, for real, so that anyone in the world can access it 24/7

Disk Quota

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

• You get odd error messages, especially “cannot write file”, or “disk quota exceeded”
• You cannot log in—it takes your user name and password on the machines in Phelps 3525 or CSIL, but then just logs you out immediately.

Then you probably have a disk quota problem.

• The best way to troubleshoot this, if you cannot log in, is to ask someone else that CAN log in to allow you to use a terminal window on their screen.
  • Use ssh yourusername@csil.cs.ucsb.edu to get into your account from their terminal session.
• For troubleshooting tips, visit: CSIL Disk Quota Troubleshooting

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:

• First Name
• Last Name
• Email (you may use any email address you like)
• Company (you may leave this blank).
• Preferred Development Language: We suggest you select “Java” if you are currently enrolled in CMPSC 156
  • (Don’t worry; this doesn’t prevent you from using the account with other languages later.)

Step 3: Create your repo

You should already have a repo under the course organization ucsb-cs156-f20 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-f20/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.

• First, use mvn compile to make sure that the code compiles.

  • If you get the error about JAVA_HOME not being defined correctly, you may need this command:

    export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
    

• Next, try mvn test to be sure that the test cases pass.

• Then, try mvn spring-boot:run. This should start up a web server on port 8080 running on localhost

  The mvn spring-boot:run command is a shortcut that is provided for us to be able to run the jar file. It does pretty much the same thing as if we ran the .jar file and specified the class containing our main on the command line.

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.

PORT=12345 mvn spring-boot:run

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

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.

• If you are running the code on a CSIL machine, then localhost refers to that machine.
• If you are running on your own machine, then locahost refers to that machine.
• The port number is a more specific “communications channel” on that machine. You can find more information on port numbers at this short article, which you are encouraged to read if you are not already familiar with port numbers (or, for that matter, even if you are): https://ucsb-cs56.github.io/topics/port_numbers/

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

• Note: You should use http not https when running on localhost. Using http is the unsecure, unencrypted version.
• It is possible to set up Spring Boot to run https (the secure, encrypted version), but it’s complicated and typically unnecessary; Heroku sets up https for us automatically, so we really don’t need to deal with those steps most of the time.

Step 5: Undertstanding localhost vs. Heroku

When running on localhost:

• The web app is only runnning as long as your program is executing.
• As soon as you CTRL/C the program to interrupt it, the web app is no longer available.
• The web app is only available on the machine where you are running the program; not on the public internet.

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.

Logged into CSIL (or one of the machines in the CSTL, i.e. Phelps 3525), use this command to login to Heroku at the command line:

heroku login

NOTES:

• If you are ssh’ing in to CSIL, you may need to use heroku login -i which allows you to login without having to go to a browser.

• If the heroku login command doesn’t work, you can instead create the Heroku App at the Heroku Dashboard by visiting https://dashboard.heroku.com/apps, clicking (at upper right): “New => Create New App” and then creating an app with the name jpa02-ucsbnetid as explained in the instructions below.

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:

• A reminder that this is an individual lab, so you should complete it for yourself, i.e. there is only one github id in the name, not a pair of github ids.
• Please do not literally put the letters githubid in your app name; you are meant to substitute your own github id there.
• If Heroku indicates that the name is too long, you may truncate any part of it.

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 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!";

        return "Greetings from Spring Boot!";

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

Then:

• use mvn compile to make sure your code still compiles
• (optional, but suggested in case you need to debug)
  • use mvn spring-boot:run to test locally, perhaps with curl http://localhost:8080
• Use git add, git commit, and git push to push your changes to github.

• Visit the Heroku Dashboard, go to the Deploy tab, and scroll down to Manual Deploys. Select the main branch and click Deploy Branch to deploy your branch to the web.

  As before, wait until the script says that your branch is successfully deployed (or, if there are errors, read the error message in the log and address the errors.)

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

• The words “this github repo” should link to your github repo

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:

• src/test/java/hello/HelloControllerTest.java (Unit Test)

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 11: 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 12: Submitting your work for grading

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

If there is not yet a place to submit jpa02 on Gradescope, please come back later.

If there are any delays in deploying that autograder, the due date for the lab will be extended accordingly; you will have at least one week from the day that the autograder is tested and reliable to submit this assignment.

But you can certain start on it earlier than that.