For due date: see the jpa04 entry on Canvas: https://ucsb.instructure.com/courses/25659/assignments/357308

Instructions for jpa04

If you run into problems, let us know on the #help-jpa04 channel on the slack.

This is an individual lab on the topic of deploying Java web apps with a frontend component that also use OAuth and Databases, using Dokku.

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.

Goal

By the end of this lab, you’ll have deployed your own copy of the starter code repo (https://github.com/ucsb-cs156-s25/STARTER-jpa04) on both localhost and Dokku.

This app is a full-stack web app. The new part is:

A front-end built in React (under the directory ./frontend)
Automatic generation of Storybook/Chromatic web pages that document the React components for both the production code (main branch) and all branches that have open pull requests targetting the main branch.

In addition, we still have all of these parts that are similar to the previous lab (jpa03):

A back-end built in Spring Boot (the code for this is under the directory ./src, plus the pom.xml at the top level
OAuth integration; this allows the app to have a “login/logout” feature based on Google Accounts (e.g. your UCSB Google Account)
A SQL database, which runs using H2 (an in-memory database) on localhost, and using Postgres when running on Dokku.
Automatic generation of javadoc

This app is not intended as a coherent app to solve a real-world problem, but as a code base that demonstrates many of the techniques you would need in such an app. The legacy code apps that we’ll work with in this course have a similar structure.

Here is an example of this app, up and running. Try logging in with your UCSB Google Credentials:

https://jpa04-staff.dokku-00.cs.ucsb.edu/

If the menu looks like this, click on the hamburger icon (☰) to expose the Login button:

It should then look like this, and you should be able to login:

Once you are logged in, you’ll see a navigation bar like this one (though you will not see the Admin menu):

None of the menus will do much of anything. It turns out that the application is a shell of an application that:

allows users to login and logout using a Google account
allows the developer to configure some users as “admins”
allows admin users to see who has logged in to the app in the past (by storing each login in a database)

However, we need those basic functions as a basis to build more complex functions, and every student in the class needs to know how to configure and deploy an app on Dokku.

The configuration is mostly the same as in jpa03, so for many of these steps, we won’t repeat the instructions. Instead, refer to jpa03 for the details:

Setting up SSL (https) for your dokku app
Configuring Google OAuth (this can be tested on localhost first)
Setting up the dokku app
Connecting it to a Github repo
Configuring https
Configuring a postgres database on Dokku

So, let’s get started.

Step 1: Create your repo

There should already be a repo for you under the course organization with a name in this format:

https://github.com/ucsb-cs156-s25/jpa04-githubid

where github is your github id.

You should add a remote for the starter code from this repo:

git remote add starter https://github.com/ucsb-cs156-s25/STARTER-jpa04

Then pull in the code from the main branch of the starter repo (here: https://github.com/ucsb-cs156-s25/STARTER-jpa04) and push it to the main branch of your repo.

If you need a refresher on how to do that, please see the instructions for jpa03.

Step 2: Configure Actions and Github Pages

As you did in jpa03, please:

Enable Github Actions
Set up Github Pages

The steps are mostly the same, but there is one new aspect: setting up your repo for Chromatic access, as explained below; however, please get everything else with Github pages working first.

As a reminder, the steps for configuring Github Page are mostly documented in the README file of your starter code, but you may also refer to jpa03.

Once the basic Github Page configuration is done, you’ll notice that there are additional links on the Github Pages site for frontend components, but they probably won’t all work until you do the next couple of steps to enable Storybook/Chromatic.

So let’s proceed.

Step 2.1: Enable Chromatic

In this step, we are setting up Storybook and Chromatic.

Storybook is software that allows us to document and test the frontend of our application, one component at a time, without needing the backend at all.
Chromatic is a private company that offers free hosting for Storybook sites, as well as some paid tools for working with Storybook. We have been given complimentary access to some of those paid tools as a courtesy.

As an example of Storybook, here is a link to the storybook for the starter code:

https://67f864a308dbcc23529c76e8-hpbxoidyyg.chromatic.com/

Click the triangle to read more about why Storybook and Chromatic are useful when building a full-stack web applications.

Storybook is helpful for several reasons:

You can develop frontend components without depending on whether the backend part is working yet. This is very helpful for team projects where you may want to have different team members working on the frontend and the backend. (Note, however, that it’s very important to agree in advance on the interface between the frontend and the backend!).
You can test the frontend components separately from the backend. This is very helpful when debugging problems in the web app which are typically caused by one of three things (a) a problem in the backend, (b) a problem in the frontend (c) a error in communication between the front and backend. Having a way to isolate the frontend makes it much easier to identify the root causes of such problems.
It serves as a way of documenting the collection of user interface elements that a present in the code base. This is helpful for being able to reuse user interface components, or identify the existing part of the user interface that’s closest to the one you intend to build.
It helps to be able to identify opportunities for refactoring the user interface code to make it more consistent.

Chromatic.com, in addition to providing web hosting for Storybook sites, offers:

“… a visual testing & review tool that scans every possible UI state across browsers to catch visual and functional bugs. Assign reviewers and resolve discussions to streamline team sign-off.”

The idea is that the first time your Storybook is built, it takes a screenshot of each user element. On subsequent builds, it again takes those screenshots, and if/when any of them change, it asks whether the change should be approved or rejected. This is incorporated into the Github Action for Storybook which will remain marked with a yellow (i.e. unfinished, incomplete) until the developer reviews the changes in the user interface elements.

To configure your web app for Chromatic, you need to:

Create a Chromatic.com account (using your Github login)
Visit the page https://ucsb-cs156.github.io/topics/chromatic and follow the instructions to set up your repo as a Chromatic project.
Once it is setup as a project, you’ll be able to obtain a value for the CHROMATIC_PROJECT_TOKEN
Then, you can set up the CHROMATIC_PROJECT_TOKEN as a repository level secret, accessible to the Github Actions scripts.

Step 2.2: Check that Chromatic is building properly

Go to the Github Actions page for your repo and run the job 53-chromatic-main-branch.yml again; it may have failed on the first run for lack of a value for CHROMATIC_PROJECT_TOKEN.

When you’ve re-run the Github Action 53-chromatic-main-branch.yml, navigate to the Github Pages site for repo.

And the links for Storybook and build info should take you to pages that looks like these:

storybook	build info

Green check ✅, not red X ❌

Once you’ve completed your setup, GitHub Actions should be running on the main branch with a green check, not a red X. If there are problems there,

Step 3: Configure your app for OAuth localhost as documented in the README.md

The steps here are similar to those in jpa03, so we won’t repeat the instructions; the short version is:

read through the README.md and configure your app for oauth on localhost.

Reminders:

The .env file should not be committed to GitHub
The .env.SAMPLE file should not be changed or deleted.

Step 4: Configure your app to run on Dokku

Now follow the steps from the README.md to configure your app on dokku.

These steps to get your app up and running on Dokku are also documented here:

https://ucsb-cs156.github.io/topics/dokku/deploying_an_app.html

Once you’ve followed these instructions, try logging in to your app. It should be available at this url:

https://jpa04-yourGithubId.dokku-xx.cs.ucsb.edu

Where:

yourGithubId is your Github Id
xx is your two-digit team/dokku number

You should test the following features:

You should see be able to login with your UCSB Google account
You should see an Admin menu, where you can see the names of everyone that has logged in

What if it doesn’t work?

If it doesn’t work:

Check on the Slack channel #help-jpa04 to see if there are any known issues.
Ask folks on your own team for help first on your team’s slack channel.
Post a specific question on the #help-jpa04 slack channel—note what you were trying to do, what you expected, and what happened instead. Screenshots or copy/pasted console output is helpful!
Come to office hours (posted here: <>)
Ask during class on #help-lecture-discussion

Step 5: Enable Link to Swagger

For a production dokku deployment of a real, user-facing app, we would normally not want a link to the Swagger tool to appear. This is not functionality that a normal end user would be interacting with.

However, for developers, it is often convenient to enable this link on deployments of our app that are being used for quality assurance (QA), demos, etc.

You can enable this link by setting the following configuration variable on dokku:

dokku config:set appname SHOW_SWAGGER_UI_LINK=true

Where appname in this case is jpa04-yourGithubId.

Type that command, and when it finishes, you should be able to refresh the web page for your dokku deployment of the app and see the Swagger link in the menu bar.

Step 6: Add link to running app to your README.md file

At the top of your README.md, you’ll find this:

Follow these instructions; i.e. put in the link to your running app on Dokku, and remove the comment so that afterwards it looks something like this (but with your actual Dokku link, not the example value shown here).

Step 7: Submit on Canvas

Before submitting on Canvas, check all of the items in the grading rubric below; make sure you are in compliance with all of them.

If so, then you are ready to submit on Canvas.

Remember to submit a link to your repo, not a link to your running app.

Grading Rubric:

(10 pts) README in your repo has a link to your running web app.
(10 pts) There is a running web app at https://jpa04-githubid.dokku-xx.cs.ucsb.edu
(10 pts) Running web app has the ability to login with OAuth through a Google Account.
(10 pts) The ADMIN_EMAILS variable is set to include all staff emails (see list below) plus your own email.
- The correct setting is shown below, except with your email in place of youremail
- ADMIN_EMAILS=youremail@ucsb.edu,djensen@ucsb.edu,benjaminconte@ucsb.edu,samuelzhu@ucsb.edu,divyanipunj@ucsb.edu,sangitakunapuli@ucsb.edu,amey@ucsb.edu,phtcon@ucsb.edu
(10 pts) The link on your main repo page is set your Github Pages page (i.e. https://ucsb-cs156-s25.github.io/jpa04-yourGithubId, where yourGithubId is replaced by your Github Id. )
(10 pts) The Github Pages page shows a web page that looks like the example in the lab instructions and has the correct content.
(10 pts) Chromatic is configured correctly, and the Github Pages site has a Storybook configured properly.
(10 pts) GitHub Actions runs correctly and there is a green check (not a red X) on your main branch
(10 pts) On dokku, the Swagger link appears in the menu bar.
(10 pts) There is a post on Canvas for this assignment that has the correct content (i.e. a link to the repo, not the running app on Dokku)

Note that the Rubric above is subject to change, but if it does:

You’ll be notified during a class meeting
You’ll have an additional week from the date of the announced change to get your repo in shape with the new requirements.

Instructor Resources

Click the triangle for a list of tasks the instructor should do prior releasing this lab.

Create jpa04 repos using the https://ucsb-cs-github-linker.herokuapp.com
Set up starter code in the course organization, and update links
Create a Canvas assignment for jpa04
Make sure the app https://jpa04-staff.dokku-00.cs.ucsb.edu/ is up and running, and is sync’d with the starter code:

i.e, on dokku-00 for example, do:
```
dokku git:sync jpa04-staff https://github.com/ucsb-cs156-s25/STARTER-jpa04 main
dokku ps:rebuild jpa04-staff
```

Remove older users from the database, e.g.

dokku postgres:connect jpa04-staff-db
select * from users;
delete from users where id>2;
\q

Proofread the instructions in this file, and request that the staff (TAs/LAs do also)
Consider assigning at least one TA/LA (preferably the one with the least prior experience with the course) to complete the lab in it’s entirety to debug the starter code and instructions
Be sure that the organization settings are set like this, in, for example, https://github.com/organizations/ucsb-cs156-s24/settings/actions

This is needed so that the github actions scripts have write access to the directory.

This setting is probabaly also a good idea: