{"id":14977512,"url":"https://github.com/apereo/cas-overlay-template","last_synced_at":"2025-12-28T04:31:56.305Z","repository":{"id":38240172,"uuid":"46771779","full_name":"apereo/cas-overlay-template","owner":"apereo","description":"Apereo CAS WAR Overlay template","archived":false,"fork":true,"pushed_at":"2024-09-24T01:18:25.000Z","size":11093,"stargazers_count":1219,"open_issues_count":0,"forks_count":1046,"subscribers_count":66,"default_branch":"master","last_synced_at":"2024-09-24T22:33:34.608Z","etag":null,"topics":["authentication","cas","installation","maven","overlay","single-sign-on","spring-boot","spring-framework","sso-authentication","war","web"],"latest_commit_sha":null,"homepage":"https://apereo.github.io/cas","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"UniconLabs/simple-cas4-overlay-template","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apereo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-11-24T06:28:38.000Z","updated_at":"2024-09-24T01:18:28.000Z","dependencies_parsed_at":"2023-10-04T05:29:30.722Z","dependency_job_id":"be217602-fe2b-478a-bb47-f3832207c81d","html_url":"https://github.com/apereo/cas-overlay-template","commit_stats":null,"previous_names":[],"tags_count":254,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apereo%2Fcas-overlay-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apereo%2Fcas-overlay-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apereo%2Fcas-overlay-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apereo%2Fcas-overlay-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apereo","download_url":"https://codeload.github.com/apereo/cas-overlay-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219875683,"owners_count":16554701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","cas","installation","maven","overlay","single-sign-on","spring-boot","spring-framework","sso-authentication","war","web"],"created_at":"2024-09-24T13:55:47.923Z","updated_at":"2025-10-02T12:30:56.025Z","avatar_url":"https://github.com/apereo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IMPORTANT NOTE\u003cbr/\u003e******************************************************\u003cbr/\u003eThis repository is always automatically generated from the [CAS Initializr](https://github.com/apereo/cas-initializr). Do NOT submit pull requests here as the change-set will be overwritten on the next sync. To learn more, please visit the [CAS documentation](https://apereo.github.io/cas).\u003cbr/\u003e******************************************************\u003cbr/\u003e\nApereo CAS WAR Overlay Template\n=====================================\n\nWAR Overlay Type: `cas-overlay`\n\n# Versions\n\n- CAS Server `7.3.0-RC4`\n- JDK `21`\n\n# Build\n\nTo build the project, use:\n\n```bash\n# Use --refresh-dependencies to force-update SNAPSHOT versions\n./gradlew[.bat] clean build\n```\n\nTo see what commands/tasks are available to the build script, run:\n\n```bash\n./gradlew[.bat] tasks\n```\n\nIf you need to, on Linux/Unix systems, you can delete all the existing artifacts\n(artifacts and metadata) Gradle has downloaded using:\n\n```bash\n# Only do this when absolutely necessary\nrm -rf $HOME/.gradle/caches/\n```\n\nSame strategy applies to Windows too, provided you switch `$HOME` to its equivalent in the above command.\n\n# Keystore\n\nFor the server to run successfully, you might need to create a keystore file.\nThis can either be done using the JDK's `keytool` utility or via the following command:\n\n```bash\n./gradlew[.bat] createKeystore\n```\n\nUse the password `changeit` for both the keystore and the key/certificate entries. \nEnsure the keystore is loaded up with keys and certificates of the server.\n\n## Extension Modules\n\nExtension modules may be specified under the `dependencies` block of the [Gradle build script](build.gradle):\n\n```gradle\ndependencies {\n    implementation \"org.apereo.cas:cas-server-some-module\"\n    ...\n}\n```\n\nTo collect the list of all project modules and dependencies in the overlay:\n\n```bash\n./gradlew[.bat] dependencies\n```                                                                       \n\n# Deployment\n\nOn a successful deployment via the following methods, the server will be available at:\n\n* `https://localhost:8443/cas`\n\n\n## Executable WAR\n\nRun 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.\n\nThe current servlet container is specified as `-tomcat`.\n\n```bash\njava -jar build/libs/cas.war\n```\n\nOr via:\n\n```bash\n./gradlew[.bat] run\n```\n\nIt is often an advantage to explode the generated web application and run it in unpacked mode.\nOne way to run an unpacked archive is by starting the appropriate launcher, as follows:\n\n```bash\njar -xf build/libs/cas.war\ncd build/libs\njava org.springframework.boot.loader.launch.JarLauncher\n```\n\nThis is slightly faster on startup (depending on the size of the WAR file) than\nrunning from an unexploded archive. After startup, you should not expect any differences.\n\nDebug the CAS web application as an executable WAR:\n\n```bash\n./gradlew[.bat] debug\n```\n       \nOr via:\n\n```bash\njava -Xdebug -Xrunjdwp:transport=dt_socket,address=5000,server=y,suspend=y -jar build/libs/cas.war\n```\n\nRun the CAS web application as a *standalone* executable WAR:\n\n```bash\n./gradlew[.bat] clean executable\n```\n\n### CDS Support\n\nCDS is a JVM feature that can help reduce the startup time and memory footprint of Java applications. CAS via Spring Boot\nnow has support for easy creation of a CDS friendly layout. This layout can be created by extracting the CAS web application file\nwith the help of the `tools` jarmode:\n\n```bash\n# Note:\n# You must first build the web application with \"executable\" turned off\njava -Djarmode=tools -jar build/libs/cas.war extract\n\n# Perform a training run once\njava -XX:ArchiveClassesAtExit=cas.jsa -Dspring.context.exit=onRefresh -jar cas/cas.war\n\n# Run the CAS web application via CDS\njava XX:SharedArchiveFile=cas.jsa -jar cas/cas.war\n```\n\n## External\n\nDeploy the binary web application file in `build/libs` after a successful build to a servlet container of choice.\n\n# Docker\n\nThe following strategies outline how to build and deploy CAS Docker images.\n\n## Jib\n\nThe 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.\n\n```bash\n# Running this task requires that you have Docker installed and running.\n./gradlew build jibDockerBuild\n```\n\n## Dockerfile\n\nYou can also use the Docker tooling and the provided `Dockerfile` to build and run.\nThere are dedicated Gradle tasks available to build and push Docker images using the supplied `DockerFile`:\n\n```bash\n./gradlew build casBuildDockerImage\n```\n\nOnce ready, you may also push the images:\n\n```bash\n./gradlew casPushDockerImage\n```\n\nIf credentials (username+password) are required for pull and push operations, they may be specified\nusing system properties via `-DdockerUsername=...` and `-DdockerPassword=...`.\n\nA `docker-compose.yml` is also provided to orchestrate the build:\n\n```bash  \ndocker-compose build\n```\n\n## Spring Boot\n\nYou can use the Spring Boot build plugin for Gradle to create CAS container images.\nThe plugins create an OCI image (the same format as one created by docker build)\nby using [Cloud Native Buildpacks](https://buildpacks.io/). You do not need a Dockerfile, but you do need a Docker daemon,\neither locally (which is what you use when you build with docker) or remotely\nthrough the `DOCKER_HOST` environment variable. The default builder is optimized for\nSpring Boot applications such as CAS, and the image is layered efficiently.\n\n```bash\n./gradlew bootBuildImage\n```\n\nThe first build might take a long time because it has to download some container\nimages and the JDK, but subsequent builds should be fast.\n\n# CAS Command-line Shell\n\nTo launch into the CAS command-line shell:\n\n```bash\n./gradlew[.bat] downloadShell runShell\n```\n\n# Retrieve Overlay Resources\n\nTo fetch and overlay a CAS resource or view, use:\n\n```bash\n./gradlew[.bat] getResource -PresourceName=[resource-name]\n```\n\n# Create User Interface Themes Structure\n\nYou can use the overlay to construct the correct directory structure for custom user interface themes:\n\n```bash\n./gradlew[.bat] createTheme -Ptheme=redbeard\n```\n\nThe generated directory structure should match the following:\n\n```\n├── redbeard.properties\n├── static\n│ └── themes\n│     └── redbeard\n│         ├── css\n│         │ └── cas.css\n│         └── js\n│             └── cas.js\n└── templates\n    └── redbeard\n        └── fragments\n```\n\nHTML templates and fragments can be moved into the above directory structure, \nand the theme may be assigned to applications for use.\n\n# List Overlay Resources\n \nTo list all available CAS views and templates:\n\n```bash\n./gradlew[.bat] listTemplateViews\n```\n\nTo unzip and explode the CAS web application file and the internal resources jar:\n\n```bash\n./gradlew[.bat] explodeWar\n```\n\n# Configuration\n\n- The `etc` directory contains the configuration files and directories that need to be copied to `/etc/cas/config`.\n\n```bash\n./gradlew[.bat] copyCasConfiguration\n```\n\n- The specifics of the build are controlled using the `gradle.properties` file.\n\n## Configuration Metadata\n\nConfiguration metadata allows you to export collection of CAS properties as a report into a file \nthat can later be examined. You will find a full list of CAS settings along with notes, types, default and accepted values:\n\n```bash\n./gradlew exportConfigMetadata\n```                           \n\n# Puppeteer\n\n\u003e [Puppeteer](https://pptr.dev/) is a Node.js library which provides a high-level API to control Chrome/Chromium over the DevTools Protocol.\n\u003e Puppeteer runs in headless mode by default, but can be configured to run in full (non-headless) Chrome/Chromium.\n\nPuppeteer scenarios, used here as a form of acceptance testing, allow you to verify CAS functionality to address a particular authentication flow. The scenarios, which may be\nfound inside the `./puppeteer/scenarios` directory are designed as small Node.js scripts that spin up a headless browser and walk through a test scenario. You may\ndesign your own test scenarios that verify functionality specific to your CAS deployment or feature.\n\nTo execute Puppeteer scenarios, run:\n\n```bash\n./puppeteer/run.sh\n```\n\nThis will first attempt to build your CAS deployment, will install Puppeteer and all other needed libraries. It will then launch the CAS server,\nand upon its availability, will iterate through defined scenarios and will execute them one at a time.\n\nThe following defaults are assumed:\n\n- CAS will be available at `https://localhost:8443/cas/login`.\n- The CAS overlay is prepped with an embedded server container, such as Apache Tomcat.\n\nYou may of course need to make adjustments to account for your specific environment and deployment settings, URLs, etc.\n\n\n# Duct\n\n`duct` is a Gradle task to do quick smoke tests of multi-node CAS high-availability deployments. In particular, it tests correctness of ticket\nsharing between multiple individual CAS server nodes backed by distributed ticket registries such as Hazelcast, Redis, etc.\n\nThis task requires CAS server nodes to **enable the CAS REST module**. It will **NOT** work without it.\n\nThe task accepts the following properties:\n\n- Arbitrary number of CAS server nodes specified via the `duct.cas.X` properties.\n- URL of the service application registered with CAS specified via `duct.service`, for which tickets will be requested.\n- `duct.username` and `duct.password` to use for authentication, when requesting ticket-granting tickets.\n\nIt automates the following scenario:\n\n- Authenticate and issue a service ticket on one CAS node\n- Validate this service ticket on the another node\n- Repeat (You may cancel and stop the task at any time with `Ctrl+C`)\n\nIf the task succeeds, then we effectively have proven that the distributed ticket registry has been set up and deployed\ncorrectly and that there are no connectivity issues between CAS nodes.\n\nTo run the task, you may use:\n\n```bash\n./gradlew duct\n    -Pduct.cas.1=https://node1.example.org/cas \\\n    -Pduct.cas.2=https://node2.example.org/cas \\\n    -Pduct.cas.3=https://node3.example.org/cas \\\n    -Pduct.cas.4=https://node4.example.org/cas \\\n    -Pduct.service=https://apereo.github.io \\\n    -Pduct.username=casuser \\\n    -Pduct.password=Mellon\n```\n\nYou may also supply the following options:\n\n- `duct.debug`: Boolean flag to output debug and verbose logging.\n- `duct.duration`: Number of seconds, i.e. `30` to execute the scenario.\n- `duct.count`: Number of iterations, i.e. `5` to execute the scenario.\n\n\n# OpenRewrite\n\n[OpenRewrite](https://docs.openrewrite.org/) is a tool used by the CAS in form of a Gradle plugin\nthat allows the project to upgrade in place. It works by making changes to the project structure representing\nyour CAS build and printing the modified files back. Modifications are packaged together in form of upgrade\nscripts called `Recipes` that are automatically packaged and presented to the build and may be discovered via:\n\n```bash\n./gradlew --init-script openrewrite.gradle rewriteDiscover -PtargetVersion=X.Y.Z --no-configuration-cache | grep \"org.apereo.cas\"\n```\n\n**NOTE:** All CAS specific recipes begin with `org.apereo.cas`. The `targetVersion` must be the CAS version to which you want to upgrade.\n\nOpenRewrite recipes make minimally invasive changes to your CAS build allowing you to upgrade from one version\nto the next with minimal effort. The recipe contains *almost* everything that is required for a CAS build system to navigate\nfrom one version to other and automated tedious aspects of the upgrade such as finding the correct versions of CAS,\nrelevant libraries and plugins as well as any possible structural changes to one's CAS build.\n\nTo run, you will need to find and select the name of the recipe first. Then, you can dry-run the selected recipes and see which files would be changed in the build log.\nThis does not alter your source files on disk at all. This goal can be used to preview the changes that would be made by the active recipes.\n\n```bash\n./gradlew --init-script openrewrite.gradle rewriteDryRun -PtargetVersion=X.Y.Z -DactiveRecipe=[recipe name] --no-configuration-cache\n```\n\nWhen you are ready, you can run the actual recipe:\n\n```bash\n./gradlew --init-script openrewrite.gradle rewriteRun -PtargetVersion=X.Y.Z -DactiveRecipe=[recipe name] --no-configuration-cache\n```\n\nThis will run the selected recipes and apply the changes. This will write changes locally to your source files on disk.\nAfterward, review the changes, and when you are comfortable with the changes, commit them.\nThe run goal generates warnings in the build log wherever it makes changes to source files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapereo%2Fcas-overlay-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapereo%2Fcas-overlay-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapereo%2Fcas-overlay-template/lists"}