We will use the Maven WAR overlay template provided by the CAS project as the starting point for our own project.

Clone the overlay template project

Use Git to clone the overlay template project from GitHub. Run the commands

casdev-master# cd /opt/workspace
casdev-master# git clone https://github.com/apereo/cas-overlay-template.git
Cloning into 'cas-overlay-template'...
remote: Counting objects: 610, done.
remote: Compressing objects: 100% (12/12), done.
remote: Total 610 (delta 7), reused 12 (delta 4), pack-reused 594
Receiving objects: 100% (610/610), 198.63 KiB | 0 bytes/s, done.
Resolving deltas: 100% (298/298), done.
casdev-master#

on the master build server (casdev-master). This will make a local copy of all files in the template project and store them in a directory called cas-overlay-template. It will also record the information needed for Git to keep the local copy of the files synchronized with the copy stored on GitHub, so that corrections and updates made by the project team can be incorporated into our project from time to time.

Switch to the right branch

The GitHub repository for the overlay template project contains multiple versions of the template; each version is stored as a separate branch of the project. The master branch usually points to the version of the template used for configuring and deploying the latest stable release of the CAS server; this is the branch that will initially be copied to disk by cloning the project. Run the commands

casdev-master# cd cas-overlay-template
casdev-master# grep '<cas.version>' pom.xml
        <cas.version>5.2.0</cas.version>
casdev-master#

to determine which version of the CAS server the master branch will build. In most circumstances (including this project), the master branch of the template is the one you want to use (skip ahead to the next section, Create a local branch).

If the master version of the template isn’t for the version of the CAS server you want to work with (for example, if you want to work with an older version, or experiment with the version currently under development), run the command

casdev-master# git branch -a
* master
  remotes/origin/4.1
  remotes/origin/4.2
  remotes/origin/5.0.x
  remotes/origin/5.1
  remotes/origin/5.2
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
casdev-master#

to obtain a list of available branches, and then run the git checkout command to switch to that branch. For example, to switch back to the 5.1 branch, run the command

casdev-master# git checkout 5.1
Branch 5.1 set up to track remote branch 5.1 from origin.
Switched to a new branch '5.1'
casdev-master#  grep '<cas.version>' pom.xml
        <cas.version>5.1.5</cas.version>
casdev-master#

to switch branches (it’s not necessary to type the remotes/origin/ part of the branch name). This will download additional/changed files from GitHub to the local disk. You can switch back to the current version of the template by checking out the master branch again:

casdev-master# git checkout master
Switched to branch 'master'
casdev-master#  grep '<cas.version>' pom.xml
        <cas.version>5.2.0</cas.version>
casdev-master#

Create a local branch

After you’re on the right branch (for our project, you should be on the master branch), create a new branch local to your project, which will be used to track all of your changes and keep them separate from any changes made to the template by the CAS developers. This will make it easier in the future to merge upstream changes from the CAS project team into your local template without having to redo all your changes.

Choose a meaningful name for your branch, but not somthing likely to be duplicated by the CAS developers—for example, newschool-casdev. Run the commands

casdev-master# git checkout -b newschool-casdev
Switched to a new branch 'newschool-casdev'
casdev-master#

to create this new branch (replace newschool-casdev with the name of your branch).