To learn more, please visit the CAS documentation.

Apereo CAS WAR Overlay Template (Custom)

WAR Overlay Type: cas-overlay

Versions

• CAS Server 6.6.4
• JDK 11

Install JDK

Install the required JDK 11 here

Check your current Java version

java -version

If different from version 11 then check if it is installed

# Mac
/usr/libexec/java_home -V
# Windows
where java

Then switch the version for the current command prompt/terminal session

# Mac
export JAVA_HOME=`/usr/libexec/java_home -v 11`
# Windows
set JAVA_HOME "C:\Program Files\Java\your_jdk11_directory"

On Linux you can view/switch the default JDK with

# Linux
update-alternatives --config java

Build

To build the project, use:

# Use --refresh-dependencies to force-update SNAPSHOT versions
./gradlew[.bat] clean build

To see what commands/tasks are available to the build script, run:

./gradlew[.bat] tasks

If you need to, on Linux/Unix systems, you can delete all the existing artifacts (artifacts and metadata) Gradle has downloaded using:

# Only do this when absolutely necessary
rm -rf $HOME/.gradle/caches/

Same strategy applies to Windows too, provided you switch $HOME to its equivalent in the above command.

Keystore

For the server to run successfully, you might need to create a keystore file. This can either be done using the JDK's keytool utility or via the following command:

# If permission denied, run with admin (sudo) privilege
./gradlew[.bat] createKeystore

Use the password changeit for both the keystore and the key/certificate entries. Ensure the keystore is loaded up with keys and certificates of the server.

Extension Modules

Extension modules may be specified under the dependencies block of the Gradle build script:

dependencies {
    implementation "org.apereo.cas:cas-server-some-module"
    ...
}

To collect the list of all project modules and dependencies in the overlay:

./gradlew[.bat] dependencies

To see a full list of all project dependencies that are available for configuration and use:

curl https://localhost:8080/dependencies

Or:

curl https://localhost:8080/actuator/info

Deployment

On a successful deployment via the following methods, the server will be available at:

• https://localhost:8443/cas

For login, use the default username casuser & password Mellon

Executable WAR

Run the server web application as an executable WAR. Note that running an executable WAR requires CAS to use an embedded container such as Apache Tomcat, Jetty, etc.

./gradlew[.bat] run

Debug the CAS web application as an executable WAR:

./gradlew[.bat] debug

Run the CAS web application as a standalone executable WAR:

./gradlew[.bat] clean executable

Configuration

• Configure the allowed json services in src/main/resources/services

• Configure the app properties in src/main/resources/application.yml

• The specifics of the build are controlled using the gradle.properties file

Configuration Metadata

Configuration metadata allows you to export collection of CAS properties as a report into a file that can later be examined. You will find a full list of CAS settings along with notes, types, default and accepted values:

./gradlew exportConfigMetadata

Docker

The following strategies outline how to build and deploy CAS Docker images.

Jib

The overlay embraces the Jib Gradle Plugin to provide easy-to-use out-of-the-box tooling for building CAS docker images. Jib is an open-source Java containerizer from Google that lets Java developers build containers using the tools they know. It is a container image builder that handles all the steps of packaging your application into a container image. It does not require you to write a Dockerfile or have Docker installed, and it is directly integrated into the overlay.

# Running this task requires that you have Docker installed and running.
./gradlew build jibDockerBuild

Dockerfile

You can also use the native Docker tooling and the provided Dockerfile to build and run.

chmod +x *.sh
./docker-build.sh
./docker-run.sh

For convenience, an additional docker-compose.yml is also provided to orchestrate the build:

docker-compose build

CAS Command-line Shell

To launch into the CAS command-line shell:

./gradlew[.bat] downloadShell runShell

Retrieve Overlay Resources

To fetch and overlay a CAS resource or view, use:

./gradlew[.bat] getResource -PresourceName=[resource-name]

Create User Interface Themes Structure

You can use the overlay to construct the correct directory structure for custom user interface themes:

./gradlew[.bat] createTheme -Ptheme=redbeard

The generated directory structure should match the following:

├── redbeard.properties
├── static
│ └── themes
│     └── redbeard
│         ├── css
│         │ └── cas.css
│         └── js
│             └── cas.js
└── templates
    └── redbeard
        └── fragments

HTML templates and fragments can be moved into the above directory structure, and the theme may be assigned to applications for use.

List Overlay Resources

To list all available CAS views and templates:

./gradlew[.bat] listTemplateViews

To unzip and explode the CAS web application file and the internal resources jar:

./gradlew[.bat] explodeWar