Learningpaths: Introduction

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.

Outcomes

After completing the lab, you will have an environment with the
following:

Your lab codebase set up on a local workstation
Your GitHub repository will be set up with a Personal Access Token.

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.

Project structure and codebase

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.

VMware 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, VMware 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.

Git

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.

GitHub

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.

Bootstrap a Gradle project

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'

Tanzu Application Service (Tanzu Application Service) command line interface (CLI)

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
```

CF target

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.

Wrap up

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.

Git primer

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.

Navigating the codebase

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"
```

Git ignored files

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:
- built artifacts
- temporary files
- editor or IDE generated files

View a solution

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>
```

Comparing your workspace to a solution

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.

Checking out a file from a solution

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.

Clean your workspace

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.

Staging and committing your changes

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.

Fast-forward

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.