diff options
author | lukegb <lukegb@tvl.fyi> | 2020-07-05T19·21+0000 |
---|---|---|
committer | lukegb <lukegb@tvl.fyi> | 2020-07-05T19·21+0000 |
commit | 4b9fde0abe01bb09e0c30402ce89ff02bc0afb49 (patch) | |
tree | a43500d29b629314fc12f514c6b6714a214fb20b /third_party/apereo-cas/overlay/README.md | |
parent | 8f4dea27a6561a30e4044d532a76e716c6cbf75b (diff) | |
parent | c22796eb2a4c9e9f04dcc098c7705a6ddfce81a5 (diff) |
Merge "merge(3p/apereo-cas-overlay): Merge commit '2e185f50c38db1a85f39a6bd5ad4c4e58462f003' as 'third_party/apereo-cas/overlay'" into canon r/1218
Diffstat (limited to '')
-rw-r--r-- | third_party/apereo-cas/overlay/README.md | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/third_party/apereo-cas/overlay/README.md b/third_party/apereo-cas/overlay/README.md new file mode 100644 index 000000000000..ec8d96483616 --- /dev/null +++ b/third_party/apereo-cas/overlay/README.md @@ -0,0 +1,146 @@ +CAS Overlay Template [![Build Status](https://travis-ci.org/apereo/cas-overlay-template.svg?branch=master)](https://travis-ci.org/apereo/cas-overlay-template) +======================= + +Generic CAS WAR overlay to exercise the latest versions of CAS. This overlay could be freely used as a starting template for local CAS war overlays. + +# Versions + +- CAS `6.2.x` +- JDK `11` + +# Overview + +To build the project, use: + +```bash +# Use --refresh-dependencies to force-update SNAPSHOT versions +./gradlew[.bat] clean build +``` + +To see what commands are available to the build script, run: + +```bash +./gradlew[.bat] tasks +``` + +To launch into the CAS command-line shell: + +```bash +./gradlew[.bat] downloadShell runShell +``` + +To fetch and overlay a CAS resource or view, use: + +```bash +./gradlew[.bat] getResource -PresourceName=[resource-name] +``` + +To list all available CAS views and templates: + +```bash +./gradlew[.bat] listTemplateViews +``` + +To unzip and explode the CAS web application file and the internal resources jar: + +```bash +./gradlew[.bat] explodeWar +``` + +# Configuration + +- The `etc` directory contains the configuration files and directories that need to be copied to `/etc/cas/config`. + +```bash +./gradlew[.bat] copyCasConfiguration +``` + +- The specifics of the build are controlled using the `gradle.properties` file. + +## Adding Modules + +CAS modules may be specified under the `dependencies` block of the [Gradle build script](build.gradle): + +```gradle +dependencies { + compile "org.apereo.cas:cas-server-some-module:${project.casVersion}" + ... +} +``` + +To collect the list of all project modules and dependencies: + +```bash +./gradlew[.bat] allDependencies +``` + +### Clear Gradle Cache + +If you need to, on Linux/Unix systems, you can delete all the existing artifacts (artifacts and metadata) Gradle has downloaded using: + +```bash +# 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. + +# Deployment + +- Create a keystore file `thekeystore` under `/etc/cas`. Use the password `changeit` for both the keystore and the key/certificate entries. This can either be done using the JDK's `keytool` utility or via the following command: + +```bash +./gradlew[.bat] createKeystore +``` + +- Ensure the keystore is loaded up with keys and certificates of the server. + +On a successful deployment via the following methods, CAS will be available at: + +* `https://cas.server.name:8443/cas` + +## Executable WAR + +Run the CAS web application as an executable WAR: + +```bash +./gradlew[.bat] run +``` + +Debug the CAS web application as an executable WAR: + +```bash +./gradlew[.bat] debug +``` + +Run the CAS web application as a *standalone* executable WAR: + +```bash +./gradlew[.bat] clean executable +``` + +## External + +Deploy the binary web application file `cas.war` after a successful build to a servlet container of choice. + +## Docker + +The following strategies outline how to build and deploy CAS Docker images. + +### Jib + +The overlay embraces the [Jib Gradle Plugin](https://github.com/GoogleContainerTools/jib) 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. + +```bash +./gradlew build jibDockerBuild +``` + +### Dockerfile + +You can also use the native Docker tooling and the provided `Dockerfile` to build and run CAS. + +```bash +chmod +x *.sh +./docker-build.sh +./docker-run.sh +``` |