lab00_sb : Deployment Practice: Spring Boot

num ready? description assigned due
lab00_sb false Deployment Practice: Spring Boot Mon 04/13 04:00PM Wed 04/22 11:59PM

This page describes detailed steps for completing lab00 using Spring Boot.

Please complete Steps 1-5 on the lab00 page first.

Step 6: 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.

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 7: 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 8: Add remote for starter code

If you followed Step 1-5 lab00, you should now be at a terminal prompt, and your current directory should be the repo you created for lab00, with a name such as cgaucho_lab00.

The next step is to add a git remote for your starter code.

git remote add starter https://github.com/ucsb-cs48-s20/demo-spring-google-oauth-app

Explanation of the git remote command

If you know the command git push origin master, in this command:

A remote refers to the location of a repository other than the current local repository (the one on your local filesystem.) By convention, when you git clone a repository, it creates a remote called origin that points back to where you cloned the repo from.

We are going to add another remote for the starter code. You’ll only pull from this remote once; you won’t have permission to push to it.

Step 9: Pull remote into local repo

Now, we are going to pull from the starter code remote into the local repo, and then push to the origin repo

git pull starter master
git push origin master

At this point, you should be able to visit the github organization (https://github.com/) and see your repo listed as one of the private repos to which you have access (you won’t see it unless you are logged in to your github account.) You should also see that it has all of the files from the starter repo.

Step 10: See example of completed app

The example app here shows what the app looks like when it is fully deployed on the web.

Try logging into this app with any Google account you have (e.g. your UCSB Email Account).

You should be able to login, logout. You won’t be able to see the admin features, because you aren’t an admin, but if you want to try those out, ask either the instructor or the TA to add you as an admin.

Once you’ve complete the steps in this lab, you should be able to:

Now that we know what we are trying to accomplish, let’s proceed.

Step 11: Install Java 11 and Maven on your machine

If you are working on CSIL, you may skip this step, because as of this writing (April 12, 2020), Java 11 and Maven are both installed on CSIL.

Otherwise, follow the instructions here for installing Java 11 and Maven

Special note for Windows Subsystem for Linux (WSL)

If you are using Windows Subsystem Linux (WSL), an error The environment variable JAVA_HOME is not correctly set may appear when you try to use Java tools. If this does occur a temporary fix is this:

Step 12: Type mvn compile to try compiling the app

We will use Maven (the mvn command) to work with Spring Boot.

Type mvn compile to try compiling the app.

For a crash course in Maven, read this: https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

Step 13: Explanation of “running on localhost”

Running on localhost is also known as development mode

If you know what is meant by “running on `localhost’” you can skip the following explanation, and go straight to the next step.

Otherwise, read this article: https://ucsb-cs48.github.io/topics/localhost/. It contains important information about common problems that can arise when running on localhost, and how to address them.

Step 14: Configuration of OAuth for Localhost

The example repo uses Google OAuth for logins/logouts. Before we can run the application on localhost, we need to do some configuration.

This configuration is explained here: https://ucsb-cs48.github.io/topics/oauth_google_setup/

Step 15: Test application on localhost

The instructions for running are in the README.md file of the starter repo, which you can read here: https://github.com/ucsb-cs48-s20/demo-spring-google-oauth-app/blob/master/README.md

The basic command is mvn spring-boot:run

Start up your server and verify that you can interact with it on localhost:8080 in the same ways you interacted with the sample implementation at https://demo-spring-google-oauth-app.herokuapp.com/

At first, you won’t able to access the admin functions. We’ll fix that in the next step

Step 16: Test application as an admin on localhost

Now, let’s configure yourself as an admin, and run the app again.

The admins for the sample code are configured in a file called src/main/resources/application.properties.

If you open up that file, you’ll see that it contains this line:

app.admin.emails=phtcon@ucsb.edu,scottpchow@ucsb.edu

There are two ways to add yourself as an admin:

  1. Add your email (any Gmail account) to the end of this comma separated list.
  2. Override this property value in either your secrets-localhost.properties or secrets-heroku.properties file, or both.

Essentially, any property defined in application.properties can be overridden for localhost or for heroku by specifying a new value in secrets-localhost.properties or secrets-heroku.properties

Make this change (whichever way you prefer), and then see if you can access the admin features of the application. You should see a menu for Users and one for Admins.

If it works, proceed to the next step.

Step 17: Understanding GitHub Actions

At this point, if you look at your GitHub repo, you’ll probably see that there is an green check next to the commit hash on the main page.

The green check signifies that GitHub Action is running test cases on your repo and they are passing.

After each commit it pushed, this first be a yellow circle, indcating that the tests are still running. It should then change to a green check.

If, instead, you see a red X, then something is wrong with the tests. In this case, ask for help; that shouldn’t be happening for this simple “getting started” lab.

Step 18: Configure application to run on Heroku

In this step, we put the application online on the public web, using a service known as Heroku

We will also refer to this as “running in production”, since it is a public facing version of our running code, running 24/7 on a web server in the cloud.

Login to https://dashboard.heroku.com/apps and click to create a new Heroku App.

Call it create cs56-S20-githubid-lab00_sb

Then go to the Deploy tab. 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”.

You should see a log of the deployment in the screen. When it is finished, there will be an “Open App” button where you can open up the URL for your app.

The app will probably crash the first time you try to bring it up. This because you need to do one additional step, namely to configure the app for Google OAuth.

This step involves:

That step is explained in detail here: https://ucsb-cs48.github.io/topics/oauth_google_setup/

Troubleshooting

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.
  2. Try running heroku apps, and make sure your app shows up.
  3. If it does, 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.

The instructions for doing this are in the for the starter code. Follow those instructions, including the adjustments needed to configure Google OAuth for production.

Explanation of localhost vs. Heroku

If you are new to running on Heroku, you may also want to read the following explanation. If you are familiar with Heroku, you may skip it.

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 19: Submit on Gauchospace

When you have a running web app, visit https://gauchospace.ucsb.edu/courses/mod/assign/view.php?id=3766298&forceview=1 and make a submission.

In the text area, enter something like this, substituting your repo name and your Heroku app name:

repo name: https://github.com/ucsb-cs48-s20/cgaucho_lab00
on now.sh: https://cs48-cgaucho0-lab00.now.sh

Then, and this is super important, please make both of those URLs clickable urls.

The instructions for doing so are here: https://ucsb-cs48.github.io/topics/gauchospace_clickable_urls/

Grading Rubric:

TBA. It will be 100 points divided across the steps in the lab.