You are viewing the development documentation for the Apereo CAS server. The functionality presented here is not officially released yet. This is a work in progress and will be continually updated as development moves forward. To view the documentation for a specific Apereo CAS server release, please choose an appropriate version. The release schedule is also available here.
This page documents the steps that a CAS developer/contributor should take for building a CAS server locally.
If you are about to deploy and configure CAS, you are in the WRONG PLACE! To deploy CAS locally, use the WAR Overlay method described in the project documentation for a specific CAS version. Cloning, downloading and building the CAS codebase from source is ONLY required if you wish to contribute to the development of the project.
The following shell commands may be used to grab the source from the repository:
1 git clone --recursive email@example.com:apereo/cas.git cas-server
Or a quicker clone:
1 2 git clone --recursive --depth=1 --single-branch --branch=master firstname.lastname@example.org:apereo/cas.git cas-server # git fetch --unshallow
For a successful clone, you will need to have set up SSH keys for your account on Github.
If that is not an option, you may clone the CAS repository under
You may also need to update submodules linked to the CAS repository. Newer versions of Git will do this automatically, but older versions will require you to explicitly tell git to download the contents of submodules:
1 git submodule update --init --recursive
The following shell commands may be used to build the source:
1 2 cd cas-server git checkout master
When done, you may build the codebase via the following command:
1 ./gradlew build install --parallel -x test -x javadoc -x check --build-cache --configure-on-demand
The following commandline boolean flags are supported by the build and can be passed in form of system properties via
||Allows for remote debugging via a pre-defined port (i.e.
||Enable Gradle’s incremental compilation feature.|
||Let the build output logs that are sent to the standard streams. (i.e. console, etc)|
||Skip running Checkstyle checks.|
||Skip running Spotbugs checks.|
||If a dependency conflict is found, use the latest version rather than failing the build.|
||Skip generating configuration metadata for nested properties and generic collections.|
||Ignore reporting results to Sonarqube.|
||Skip running the
||Do not apply the Spring Boot plugin to bootify application artifacts.|
||Ignore javadoc failures and let the build resume.|
||Ignore Findbugs failures and let the build resume.|
||Ignore test failures and let the build resume.|
||Comma separated list of modules without the
- You can use
-x <task>to entirely skip/ignore a phase in the build. (i.e.
- If you have no need to let Gradle resolve/update dependencies and new module versions for you, you can take advantage of the
--offlineflag when you build which tends to make the build go a lot faster.
- Using the Gradle daemon also is a big help. It should be enabled by default.
- Enabling Gradle’s build cache via
--build-cachecan also significantly improve build times.
Available build tasks can be found using the command
CAS development may be carried out using any modern IDE that supports Gradle.
The following IDEA settings for Gradle may also be useful:
Additionally, you may need to customize the VM settings to ensure the development environment can load and index the codebase:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 -server -Xms1g -Xmx8g -Xss16m -XX:NewRatio=3 -XX:ReservedCodeCacheSize=240m -XX:+UseCompressedOops -XX:SoftRefLRUPolicyMSPerMB=50 -XX:+UseParNewGC -XX:ParallelGCThreads=4 -XX:+UseConcMarkSweepGC -XX:ConcGCThreads=4 -XX:+CMSClassUnloadingEnabled -XX:+CMSParallelRemarkEnabled -XX:CMSInitiatingOccupancyFraction=65 -XX:+CMSScavengeBeforeRemark -XX:+UseCMSInitiatingOccupancyOnly -XX:MaxTenuringThreshold=1 -XX:SurvivorRatio=8 -XX:+UseCodeCacheFlushing -XX:+AggressiveOpts -XX:-TraceClassUnloading -XX:+AlwaysPreTouch -XX:+TieredCompilation -Djava.net.preferIPv4Stack=true -Dsun.io.useCanonCaches=false -Djsse.enableSNIExtension=true -ea -Xverify:none
The following plugins may prove useful during development:
Once you have installed the Lombok plugin, you will also need to ensure Annotation Processing is turned on. You may need to restart IDEA in order for changes to take full effect.
Note that the CAS-provided Checkstyle rules can be imported into idea to automate a number of formatting rules specially related to package imports and layouts. Once imported, the rules should look something like the below screenshot:
It is possible to run the CAS web application directly from IDEA by creating a Run Configuration that roughly matches the following screenshot:
For Eclipse, execute the following commands:
1 2 cd cas-server ./gradlew eclipse
Then, import the project into eclipse using “General\Existing Projects into Workspace” and choose “Add Gradle Nature” from the “Configure” context menu of the project.
We have had a less than ideal experience with Eclipse and its support for Gradle-based projects. While time changes everything and docs grow old, it is likely that you may experience issues with how Eclipse manages to resolve Gradle dependencies and build the project. In the end, you're welcome to use what works best for you as the ultimate goal is to find the appropriate tooling to build and contribute to CAS.
To test the functionality provided by a given CAS module, execute the following steps:
- For the tomcat, undertow or jetty webapp, add the module reference to the
webapp.gradlebuild script of web application you intend to run:
1 implementation project(":support:cas-server-support-modulename")
Alternatively, set a
casModules property in the root project’s
~/.gradle/gradle.properties to a comma separated list of modules without the
1 2 3 4 casModules=core-monitor,\ support-ldap,\ support-x509,\ support-bootadmin-client
Or set the property on the command-line:
1 bc -PcasModules=support-ldap,support-x509
bc is an alias for building CAS.
- Prepare the embedded container, as described below, to run and deploy the web application
The CAS project comes with a number of built-in modules that are pre-configured with embedded servlet containers such as Apache Tomcat, Jetty, etc for the server web application, the management web application and others. These modules are found in the
webapp folder of the CAS project.
thekeystore file must include the SSL private/public keys that are issued for your CAS server domain. You will need to use the
keytool command of the JDK to create the keystore and the certificate.
The following commands may serve as an example:
1 keytool -genkey -alias cas -keyalg RSA -validity 999 -keystore /etc/cas/thekeystore -ext san=dns:$REPLACE_WITH_FULL_MACHINE_NAME
Note that the validity parameter allows you to specify, in the number of days, how long the certificate should be valid for. The longer the time period, the less likely you are to need to recreate it. To recreate it, you’d need to delete the old one and then follow these instructions again. You may also need to provide the Subject Alternative Name field, which can be done with
The response will look something like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 Enter keystore password: changeit Re-enter new password: changeit What is your first and last name? [Unknown]: $REPLACE_WITH_FULL_MACHINE_NAME (i.e. mymachine.domain.edu) What is the name of your organizational unit? [Unknown]: Test What is the name of your organization? [Unknown]: Test What is the name of your City or Locality? [Unknown]: Test What is the name of your State or Province? [Unknown]: Test What is the two-letter country code for this unit? [Unknown]: US Is CN=$FULL_MACHINE_NAME, OU=Test, O=Test, L=Test, ST=Test, C=US correct? [no]: yes
/etc/hosts file (on Windows:
C:\Windows\System32\Drivers\etc\hosts), you may also need to add the following entry:
1 127.0.0.1 mymachine.domain.edu
The certificate exported out of your keystore needs to also be imported into the Java platform’s global keystore:
1 2 3 4 5 # Export the certificate into a file keytool -export -file /etc/cas/config/cas.crt -keystore /etc/cas/thekeystore -alias cas # Import the certificate into the global keystore sudo keytool -import -file /etc/cas/config/cas.crt -alias cas -keystore $JAVA_HOME/lib/security/cacerts
JAVA_HOME is where you have the JDK installed (i.e
On Windows, Administration right should be granted to the console instead of sudo, and
$JAVA_HOME/lib/security/cacerts should be changed to
Execute the following command:
1 2 3 cd webapp/cas-server-webapp-tomcat ../../gradlew build bootRun --parallel --offline --configure-on-demand --build-cache --stacktrace
The response will look something like this:
1 2 3 ... 2017-05-26 19:10:46,470 INFO [org.apereo.cas.web.CasWebApplication] - <Started CasWebApplication in 21.893 seconds (JVM running for 36.888)> ...
By default CAS will be available at
The embedded container instance is pre-configured to listen to debugger requests on port
5000 provided you specify the
enableRemoteDebugging parameter. For external container deployments, such as Apache Tomcat, the following example shows what needs configuring in the
1 2 3 export JPDA_ADDRESS=5000 export JPDA_TRANSPORT=dt_socket bin/catalina.sh jpda start
When you’re done, create a remote debugger configuration in your IDE that connects to this port and you will be able to step into the code.
Manual Submodule Testing
To simplify the test execution process, you may take advantage of the
testcas.sh script found at the root of the repository as such:
1 2 # chmod +x ./testcas.sh ./testcas.sh --category <category> [--test <test-class>] [--debug] [--coverage]
To learn more about the script, use:
1 ./testcas.sh --help
Sample Build Aliases
Below are some examples of convenient build aliases for quickly running a local cas server from the project or installing dependencies from the project for use in the cas-overlay.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 # adjust the cas alias to the location of cas project folder alias cas='cd ~/Workspace/cas' # test cas directly from project rather than using the CAS overlay alias bc='clear; cas; cd webapp/cas-server-webapp-tomcat ; \ ../../gradlew build bootRun --configure-on-demand --build-cache --parallel \ -x test -x javadoc -x check -DremoteDebuggingSuspend=false -DenableRemoteDebugging=true --stacktrace \ -DskipNestedConfigMetadataGen=true -DskipGradleLint=true -Dcas.standalone.configurationDirectory=/etc/cas/config' # install jars for use with a CAS overlay project alias bci='clear; cas; \ ./gradlew clean build install --configure-on-demand --build-cache --parallel \ -x test -x javadoc -x check --stacktrace \ -DskipNestedConfigMetadataGen=true -DskipGradleLint=true \ -DskipBootifulArtifact=true'