Skip to content

HW Assignment 4 Tutorial

Overview

This tutorial explains how to deploy and develop a Heroku app through GitHub that can run a React Front End. The tutorial covers creating GitHub and Heroku accounts, deploying your app via Heroku, and developing your web app locally. To work through this tutorial, you will need to be connected to the internet, you will need to be comfortable issuing commands through a command-line terminal interface, be comfortable with the git version control system, and you will need to know how to program in javascript, node.js, and react.js.

Prelude

We will be using GitHub Classroom to help manage the GitHub repositories for this assignment, and we also cover the basics of using it in this tutorial.

Please take a moment to explore each concept, technology, command, activity, and action used in this tutorial. We try to strike a balance between brevity and completeness, and welcome feedback and suggestions. (Feel free to make an Ed post if you have questions!)

Additionally, check out Dr. Moran's Week 9 lecture video, where he covered many of the basics of getting started with Homework 4 using React.

Create GitHub and Heroku Accounts

The first thing that you need to do is create free accounts for both GitHub and Heroku.

  • You can sign up for a free GitHub account account using this link.
  • You can sign up for a free Heroku account account using this link.

Joining the Assignment in GitHub Classroom

Accepting the Assignment

In order help organize the repos for the second homework assignment, we will be making use of GitHub Classroom. By "accepting" the assignment in GitHub Classroom, the service will automatically create a copy of the repository with the starter code that we covered in class. This will help get you up and running for this assignment. To "accept" the assignment, please click on the button below. (Note that you will be prompted to sign in to your GitHub account if you haven't already)

Note

It is important to note that you should only work out of this repository for this assignment. We will grade the last commit made before the deadline (see the hw4 assignment page for more details). If you make a commit after the deadline, we will grade that instead and your assignment will be considered late.

Warning

Note that the repo that is created is not associated with your GitHub username. Instead, it is associated with the GMU-SWE432-F21 GitHub Organization and your GitHub user is granted access. Therefore, it may not show up in the usual places where you find your personal repos in GitHub. Once you are added to the organization (see next instructions) it will be easy to access (You can do this by access the organizations page of your account). However, we also encourage you to bookmark link to the repository generated by GitHub Classroom.

Starter Project Structure

In order to give you an overview of the starter project, below, we provide the details regarding the most important included files below:

  • Configuration Files - Note that this React project also has its own package.json file as well as a few other configuration files.
  • src This directory contains the source code for our React App.
    • App.js - This is the main .js file for your React project and will contain most of the logic for the application.
    • App.css - This is a css file that you can use to apply various CSS styles of the different parts of your React components.
    • App.test.js - This file contains tests for the front-end of your application.
    • index.js - This file imports our application and react components and then renders them on the screen.
    • index.css - This file allows you to apply general css styling to your application.

Understanding Continuous Integration with GitHub Actions

Currently, the starter repo is configured to run your Jest tests each time you push your code to the repository (See Section 5 for more information about how to push changes to your repo). This form of automated testing is a type of continuous integration (CI). Continuous integration is essentially the practice of automating the integration of code changes from contributors to a software project, and is generally considered to be a DevOps best practice.

Here we are using a simple form of CI, as your automated Jest tests will run each time you modify code and update your Github repo with the changes. As we will see in the next section ,we will configure Heroku to only deploy the application if your automated tests pass. We are enabling the automated tests using GitHub Actions. We will touch on this more later in this tutorial.

Note

Note that since they are not required for this assignment, you can disable the CI tests running by deleting the .github folder from your repository.

Deploying your Web App via Heroku

Now that you have been granted access to the HW Assignment #4 starter repo through GitHub Classroom you are ready to deploy the starter web application using Heroku.

Your Heroku app contains all the javascript files that you will deploy for your microservice. The name you choose becomes part of the URL address to your web apps. For instance, you can access an example web-app at https://swe-432-hw4.herokuapp.com for the example illustrated in this section.

First you should sign into your Heroku account and navigate to the dashboard landing page illustrated below.

Splash screen navigating to AVD Manager

Then you should click on the "Create New App" button highlighted in red. This will bring you to the screen displayed below.

Splash screen navigating to AVD Manager

Next, you should create a name for your application. We would like you to adhere to the following naming convention when creating your app: <firstname-lastname>-swe432-hw4. For example if Dr. Moran were creating his Heroku app, he would use kevin-moran-swe432-hw4, as shown in the example url at the beginning of this section. After this you should click on the "Create App" button. Doing that should bring you to the screen shown below.

Splash screen navigating to AVD Manager

Next you will need to connect your GitHub account to Heroku. To do this, click on the GitHub button highlighted in the image above. You will then be prompted to authenticate your GitHub account and acknowledge that you are giving the Heroku service access. After that you should see the repository selection interface shown in the screen below.

Splash screen navigating to AVD Manager

Here you will need to select the repo that GitHub Classroom created for you. Therefore, you will need to select the class organization from the dropdown menu and then use the interface to search for your repository. After you select the proper repository, click on the "Connect" button to see the deployment interface as shown in the next screenshot.

Splash screen navigating to AVD Manager

After confirming your repository, you will then need to set up Heroku to deploy your application when you push to the main branch of your repository. To do this, you should "check" the option that will wait until your CI passes before deployment (this ensures you only deploy code that passes all of your tests). And then you should click on the "Enable Automatic Deployment" button. This means that each time you push to the main branch of your repository, and all of your automated tests pass, then your application will get deployed.

Finally, you can click on the "Deploy Branch" button to deploy the current version of your application.

Compile and Build Errors

Heroku compiles your code when you push it. If the compile fails, you can see the errors through the Heroku dashboard. Click the "Activity" tab, and look for a red message reading “Build failed.” Note that if your automated tests fail in GitHub, then your application will not be deployed. When you are ready to work through the next step of this tutorial, you can learn how to develop and compile locally, which is quicker and easier.

Setting Up and Using your Local Development Environment

Now that you have a GitHub repository to work from, and your web app will automatically deploy using Heroku, you need to set up an environment where you can develop and test your microservice and Front-end "locally" on your own machine. This section of the guide will walk you through the different steps and commands necessary to do so.

Note

This section of the tutorial assumes some familiarity with Git. If you are newer to using the Git version control system, I would encourage you to check out this guide.

Downloading and Installing Node.js and Git

Before we can get started with setting up your local development environment, you will need to install Node.js on your machine.

Please visit the node.js download page in order to download the version that is appropriate for your machine and operating system.

Install Git on your local machine from Git’s download site if you do not already have it installed. This will let you use the git command. For Windows, the Git download above adds bash if you do not already have it and has its own command window. If you already use cygwin, Git will add its command folder to your PATH environment variable. You can also use Windows Subsystem for Linux as mentioned earlier on in this guide.

Cloning Your repository

The first thing that you will need to do is clone the repository that GitHub Classroom created for you. To do this, navigate to your repo page and click on the "Clone" button, and then copy the url that is displayed by clicking on the clipboard icon as shown in the image below.

Splash screen navigating to AVD Manager

Next you will need to clone the repo from the command line. To do this, you can execute the following command. Note that you only need to run this command once.

1
git clone https://github.com/GMU-SWE432-F22/<your_repo_name>

Tip

Make sure you navigate to the local directory where you would like your repository to be located before you clone your repo.

Note

Note that GitHub recently changed how it handles authentication. As such, you may need to set up an ssh key, use a personal access token, or authenticate using OAuth. Check out this article for you can set up command line access. Feel free to post any questions to Ed.

Deploying your Microservice Locally

Now that you have cloned the repository by downloading it to your machine, you can deploy it locally to quickly check changes using an application such as Postman without having to push your code to GiHub and deploy to Heroku.

To deploy your application locally, you can use the following commands:

1
2
3
cd <your-repo-name> # This will move you into the proper directory
npm install # This will install all the necessary packages for React
npm start # This will start the express server and React App and listen on port 3000

This will deploy a running version of your microservice at http://localhost:3000.

Editing Code

Now that you know how to run your code locally, you can start to work on your project by editing your code!

To do this, you can use your Text Editor or IDE of choice. Some potential options include vim, Sublime Text, Atom, and VSCode among many other options. Feel free to use whatever editor you feel most comfortable with for this homework assignment.

Running your Jest Tests Locally

While the tests that you write will be automatically executed each time you commit your code to your repo, you can also run these tests locally to get an idea of their behavior before you commit and push your changes to the remote GitHub repository.

To run your tests locally, you can run the following command within the directory of your project:

1
npm test # This will run all of the tests for the React project

You will then see the output of the tests and whether or not they passed successfully.

Pushing your Local Changes to the Remote Repo

Reuse the following commands every time you need to send your changes to GitHub, in a terminal command-line window. Run these commands from your same project folder.

1
2
3
git add .
git commit -m "message explaining this commit" # A good first-time message might be: "Initial commit: first changes"
git push

The text in quotes should explain what this current commit is doing and should be clear and explicit to avoid creating maintenance debt. The idea is to document why you made the changes so that everyone who wants to contribute to your project understand, including you after a month not looking at the file.

Note

You may asked to authenticate with GitHub the first time you push. If you push again without changing anything, you will get the message “Everything up-to-date.” That's a good way to check if your repo is synchronized with your computer.

Examining Jest CI Test Results in GitHub Actions

The starter GitHub repo is set up to run the Jest tests in the App.test.js file upon each commit to the main branch of the repository. If any of the tests fail, the CI process will fail and this will be indicated with red "X" on the main page of your repo, and GitHub will likely also send you a notification email that your automated tests have failed. You can view the errors by clicking on the red "X" and checking the test logs.

Currently, the tests are configured to run via GitHub Actions by getting deployed to a remote virtual server with an Ubuntu operating system, where the npm install and npm test commands are executed. We don't anticipate you needing to change this configuration, as it is fine to keep all of your tests in the App.test.js for this assignment.

Note that we are also making use of the jest-dom library that allows you check different HTML DOM elements in your jest tests. You can find the documentation for the library here.

Note

Note that since they are not required for this assignment, you can disable the CI tests running by deleting the .github folder from your repository.

Submitting Your Assignment

Updating your Project README

In order for your assignment to be considered for grading, you must be sure that you fill out the following information at the top of your README file and ensure that this is up to date in your GitHub repo.

  • Student Name
  • Student G-number
  • Heroku Deployment URL
  • Description of your Web App and 3 React Components

Warning

Failure to include this information in your submission is likely to result in a zero for the assignment!

Submission Protocol

There is no formal submission process for this assignment. We will simply grade the last commit to the main branch of your repository before the deadline of midnight on Tuesday, Novmeber 22nd. If you make a commit after the deadline, we will grade the latest commit and your assignment will be considered late. Per our course policy, assignments submitted over 48 hours late will not be accepted.