This lab will walk you through steps necessary to set up your lab environment should you choose to run the labs.
Make sure to review the Introduction slides before proceeding.
After completing the lab, you will have an environment with the following:
You will also be able to navigate the lab codebase start and solution points, in case you wish to checkout the solution, or get stuck.
The codebase structure will include a local Git repo:
Create the following directory in your user profile,
also known as the HOME directory:
mkdir ~/workspace
NOTE:
The lab instructions assume you will run all your terminal
commands
from a bash shell.
Notice the use of the ~ shortcut for the home directory.
Navigate to the workspace sub-directory of your home directory.
Pivotal/Tanzu Labs engineers practice pair programming and rotate pairs quite frequently, usually two to three times per week. Because of this, a developer may be assigned to a different workstation on any given day. To reduce friction, Pivotal/Tanzu Labs engineers adopted this standard setup for where all project code is located.
These lab instructions will assume from now on that your code is in this directory.
Download this
pal-tracker linked zip file.
Extract the codebase in the ~/workspace directory.
The extracted pal-tracker directory will contain a single text
file as well as the (hidden) Git files.
You will be building up the code in this directory bit by bit,
and you are provided reference implementations at each stage
identified by tags in the Git repository.
The pal-tracker codebase
contains a local Git repository with the starting points and the
solutions for all the labs in this unit.
This learning path makes extensive use of the Git command line interface. You can use UI tools of your choice, but you will get better understanding of how Git works by using its CLI.
You may wonder why there is so much emphasis on Git in this learning path. That is because source control versioning and trunk-based development are fundamental to modern development practices.
If you are not proficient using the Git command line client, make sure to checkout the Git Primer section at the end of this lab.
You will use GitHub as your remote repository in this learning path, as well as GitHub Actions as your pipeline automation tool.
You will do some setup to prepare:
Create a GitHub Personal Access Token. Make sure to record this for future reference when you are prompted to authenticate to GitHub.
Create a GitHub repository called pal-tracker in your GitHub account.
Add this repository as a remote called origin of your local repository. You will push all of your work to this repository during the next few labs.
You can make the repository public or private, but do NOT select any of the initialize this repository with options.
Before your push your local repository to the remote, set up a repository scoped configuration when you authenticate to GitHub in the next step:
git config credentials.https://github.com.username <your GitHub username>
git config credential.helper cache
git config --global credential.helper 'cache --timeout=7200'
This will make sure that if you have any other GitHub or GitLab
credentials you are using on your local workstation they will not
conflict with your personal GitHub credentials you use for this
repository.
It will also cache your credentials
(after the first time you authenticate) for up to the --timeout
setting in seconds.
The example is set for 2 hours,
but you can set lower or higher values as your comfort level dictates.
You will start by pushing the initial commit to GitHub, complete with the start and solutions tags.
git push origin main --tags
You can then navigate to GitHub and view the solution tags. This is useful when you get stuck during a lab and need a little help.
You can also use GitHub’s compare functionality to compare your code to the solution.
You will use Gradle as your build and dependency management system.
Check if you have a version of Gradle installed by typing gradle
at the command-line.
If it is not currently present, follow the
official installation instructions
for your environment.
Create a Gradle wrapper
in the project root directory (~/workspace/pal-tracker) with
a gradle-version of 7.1.1 and distribution-type of all.
gradle wrapper --gradle-version 7.7.1 --distribution-type all
Create an empty build.gradle file in the same directory.
Stage and commit your changes locally with a commit message of “added gradle wrapper to initial project”:
git add ./gradle ./gradlew ./gradlew.bat ./build.gradle
git commit -m'added gradle wrapper to initial project'
You will interact with Tanzu Application Service is via the Tanzu Application Services CLI. This command-line interface is common to all products, like Tanzu Application Service, based on the (open source) Cloud Foundry technology. For this reason it is usually known as the Cloud Foundry CLI.
Verify the CLI is installed correctly by running
cf --help
which will show a list of available tasks.
If the CLI is not installed, follow the instructions for your environment. Note that the labs have been written for version 6 of the CLI.
To view more information about each task,
use the --help flag.
For example, use the following command to find more information
about the login command:
cf login --help
The CF CLI can interact with multiple installations of Tanzu Application Service so you need to target a specific installation (also called a foundation). Targeting means telling your CLI about the API endpoint for a foundation.
Use the login command to log in to your
Tanzu Application Service foundation’s API endpoint.
Verify the CLI has targeted the correct foundation by using the
target command.
You have set up your lab environment and are ready to start building an application.
Review the Concepts slides to get familiar with some basic concepts.
If you are not proficient with the Git CLI, you will get value from reviewing this section.
Becoming proficient with Git can take a long time. There are a lot of features, and many ways of doing the same things.
This learning path will use Git in specific ways, the following sub-sections list some common uses of Git that you will encounter in this learning path.
Take some time to navigate through the tags and branches using the following command:
git log --graph --decorate --oneline --all
You can also set a Git alias, lola, for this command as follows:
git config alias.lola "log --graph --decorate --oneline --all"
This will then allow you to use the command git lola as a
shortcut for the full version of the log command.
You will see start and solution tags for each of the coming labs, with the most recent commit at the top, and the initial commit at the bottom.
* 307c6b2 (tag: rolling-upgrade-solution) rolling update
* 5e66cdf (tag: scaling-availability-solution) harden cloud foundry configuration for production
* 0297055 (tag: scaling-availability-start) Add production tuning parameters to manifest, autoscaling scripts
* cd0aaa3 (tag: actuator-solution) Add actuator dependency and configuration
* a6305cf (tag: actuator-start) Add instrumentation for pal-tracker failure
* 38decca (tag: jdbc-solution) Persist time entries in database
* 00974ae (tag: jdbc-start) Add tests for persisting time entries in database
* 087905f (tag: migration-solution) Add migrations and pipeline changes
* c5a3bdf (tag: migration-start) Add task for migrating databases
* 18e4e96 (tag: mvc-solution) Add TimeEntry MVC in memory
* bc09138 (tag: mvc-start) Add tests and inmemory repo implementation for MVC lab
* 5929ac7 (tag: pipeline-solution) Update route
* 25bc37f (tag: pipeline-start) Add deployment pipeline
* 3fc69ee (tag: configuration-solution) Add manifest file for configuration and deployment to PCF
* 02e3279 (tag: configuration-start) Add tests for configuration lab
* 5457bea (tag: spring-boot-solution) Simple Spring Boot app
* 0ac8b7f (HEAD -> main, tag: spring-boot-start, origin/main, origin/HEAD) Initial commit
Notice that HEAD is pointed to the first (initial) commit.
This is the start point for the learning path,
and as you complete each lab,
you will create your own history and commits separate from the
solutions.
The --all and --graph options will show you the entire branch
history in a graphical form.
If you are only interested in seeing a summary of your current branch, you can run the following command:
git log --graph --decorate --oneline
You can also set a Git lol alias for this command as follows:
git config alias.lol "log --graph --decorate --oneline"
Take a look at the .gitignore file:
cat .gitignore
This file tells Git to ignore certain files that should not be stored in version control such as:
Sometimes you will want to look at a solution file if you get stuck.
Use the following command:
git show <solution tag>:<path to file>
An example:
You want to view the WelcomeController class you will author in
the next lesson:
git show spring-boot-solution:src/main/java/io/pivotal/pal/tracker/WelcomeController.java
The output will be the contents of the file.
You can also view all the solution commits in git diff form:
git show <solution tag>
You can run the git diff command to view differences:
View the differences in a file:
git diff <solution tag>:<path to file> <path to workspace file>
For example,
If wanting to view the difference between the build.gradle file
you created in this lab,
to the one in the next lab:
git diff spring-boot-solution:build.gradle build.gradle
The output will be in a specific git diff format, similar
to that produced by the UNIX/Linux diff -u command.
You may find IDEs have better difference viewers.
If you get stuck,
and merely want to take solution files into your workspace,
you can run the git checkout command:
Run the following:
git checkout <solution tag> <path to file>
An example:
In the next lab you will add contents to the build.gradle file
that you created earlier in this lab.
You want to go directly to the solution:
git checkout spring-boot-solution build.gradle
The outcome of running the command will be to overwrite your workspace changes with the solution, and it will be staged.
Sometimes you may want to clean your workspace, and revert to the last local committed state.
Run the following command:
git stash --include-untracked
This will save any changes that you did in a hidden,
local, private branch in case you wish to recover your work via
the git stash pop command.
If you are sure to want to throw out any stashed work permanently,
run the git stash clear command.
Many IDEs and UIs mask the local Git workflow. When using the command line, make sure you are using the following workflow when making and pushing changes to your remote:
Verify the state of your workspace with the git status command.
Unstaged changes will be highlighted in red,
staged changes will be highlighted in green.
Everything else in your workspace is either ignored
(recorded in the .gitignore file),
or already committed in your local repository.
Stage your changes with the git add command.
Run git status to verify your staged changes appear in green.
Commit your changes with the git commit command.
Add the -m option with the commit message in single or double
quotes.
Run git status to verify your committed changes no longer appear
in either staged or unchanged list.
In this learning path you will be directed to fast-forward in some of the labs by “cherry picking” Git commits or tags.
In most cases, the lab instructions will have you pull in pre-written tests or solution files that you will not have to author.
The git cherry-pick command is used to apply a pre-existing commit
into your workspace.
If you want to pull in the commit for the entire solution of a lab that you are working on, you can run the cherry-pick as follows:
git cherry-pick <solution tag>
If you want to skip certain labs, you can cherry-pick your way to it.
But there is a caveat: You must have a clean workspace, with no unstaged changed. Clean your workspace if necessary.
An example:
You want to skip ahead to the start of the Deployment Pipelines Lab after this introduction lab.
You will need to fast-forward from start of the Spring Boot application lab to the start of the deployment pipeline labs:
git cherry-pick spring-boot-solution
git cherry-pick configuration-start
git cherry-pick configuration-solution
git cherry-pick pipeline-start
Review the status of your workspace:
git status
You will see that your local history is ahead of your remote by 4 commits that you just cherry-picked:
On branch main
Your branch is ahead of 'origin/main' by 4 commits.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
Review the git log:
git log --oneline --decorate --graph --all
You will see:
4 new commits on a divergent branch from those associated with the start and solution points.
The 4 new commits have the same commit patch and commit messages as those associated with the tags cherry-picked. But they are not the same commits.
Local HEAD is pointed to the last commit generated
by the last cherry-pick,
but the remote HEAD still points to the initial
commit.
* 6fa5aa2 (HEAD -> main) Add deployment pipeline
* c6df538 Add manifest file for configuration and deployment to PCF
* 88c30fc Add tests for configuration lab
* 9f4286d Simple Spring Boot app
| * 307c6b2 (tag: rolling-upgrade-solution) rolling update
| * 5e66cdf (tag: scaling-availability-solution) harden cloud foundry configuration for production
| * 0297055 (tag: scaling-availability-start) Add production tuning parameters to manifest, autoscaling scripts
| * cd0aaa3 (tag: actuator-solution) Add actuator dependency and configuration
| * a6305cf (tag: actuator-start) Add instrumentation for pal-tracker failure
| * 38decca (tag: jdbc-solution) Persist time entries in database
| * 00974ae (tag: jdbc-start) Add tests for persisting time entries in database
| * 087905f (tag: migration-solution) Add migrations and pipeline changes
| * c5a3bdf (tag: migration-start) Add task for migrating databases
| * 18e4e96 (tag: mvc-solution) Add TimeEntry MVC in memory
| * bc09138 (tag: mvc-start) Add tests and inmemory repo implementation for MVC lab
| * 5929ac7 (tag: pipeline-solution) Update route
| * 25bc37f (tag: pipeline-start) Add deployment pipeline
| * 3fc69ee (tag: configuration-solution) Add manifest file for configuration and deployment to PCF
| * 02e3279 (tag: configuration-start) Add tests for configuration lab
| * 5457bea (tag: spring-boot-solution) Simple Spring Boot app
|/
* 0ac8b7f (tag: spring-boot-start, origin/main, origin/HEAD) Initial commit
You need to push your changes to the remote to complete the fast forward:
git push origin main
Note that the fast-forward is the for the codebase only, you will also have to push your application to Tanzu Application Service.