From 1703eca45ef94e8184c0f153b2662037aab1bc3d Mon Sep 17 00:00:00 2001 From: Ostap Zherebetskyi Date: Tue, 24 Feb 2026 12:33:55 +0200 Subject: [PATCH 1/4] Update README.md with local development instructions and ARM64 compatibility notes --- README.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 56bb2da2..aceb05a4 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,33 @@ A legacy version can be found at [CAS Overlay](https://github.com/CenterForOpenS - PostgreSQL `9.6` - JDK `11` + +# Local Development + +For local development, replace the default Dockerfile with Dockerfile-local. +This is required to ensure proper loading and usage of cas-local.properties. +```bash +cp Dockerfile-local Dockerfile +``` + +# Special Instructions for Apple Silicon (M1, M2, M3) and Other ARM64 Architectures + +If you are running Docker on ARM64 architecture (Apple Silicon or similar), you must explicitly set the platform to linux/amd64 when using OpenJDK 11 images. +Without this, the CAS container may fail to build or run correctly. + +Update the Dockerfile as follows: +```dockerfile +# Dockerfile + +FROM --platform=linux/amd64 adoptopenjdk/openjdk11:alpine-slim AS overlay +... +... + +FROM --platform=linux/amd64 adoptopenjdk/openjdk11:alpine-jre AS cas +... +``` +This forces Docker to use an amd64 image via emulation and ensures compatibility with CAS and OpenJDK 11 on ARM-based machines. + # Configure, Build and Run OSF CAS It is recommended to use the provided scripts to [build](https://github.com/CenterForOpenScience/osf-cas/blob/develop/docker-build.sh) and [run](https://github.com/CenterForOpenScience/osf-cas/blob/develop/docker-run.sh) CAS. Refer to Apereo [README.md](https://github.com/apereo/cas-overlay-template/tree/6.2#cas-overlay-template-) for more options. @@ -70,15 +97,15 @@ cas.authn.osf-postgres.jpa.dialect=io.cos.cas.osf.hibernate.dialect.OsfPostgresD The implementation of OSF CAS uses the [JPA Ticket Registry](https://apereo.github.io/cas/6.2.x/ticketing/Configuring-Ticketing-Components.html#ticket-registry) for durable ticket storage and thus requires a relational database. Set up a `PostgreSQL@9.6` server and review [JPA Ticket Registry settings](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L127-L173). In most cases, only [Database connections](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L139-L143) need to be updated. Other JDBC and JPA settings can be adjusted if necessary. -Here is an example for local development. Use `192.168.168.167` to access host outside the docker container. Use the port `54321` since the default `5432` one has been used by OSF DB. Update `pg_hba.conf` to grant proper access permission depending on the setup. +Here is an example for local development. Use `192.168.168.167` to access host outside the docker container. Update `pg_hba.conf` to grant proper access permission depending on the setup. ```yaml # In `cas.properties` or `cas-local.properties` -cas.ticket.registry.jpa.user=longzechen +cas.ticket.registry.jpa.user=postgres cas.ticket.registry.jpa.password= cas.ticket.registry.jpa.driver-class=org.postgresql.Driver -cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:54321/osf-cas?targetServerType=master +cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:5432/osf?targetServerType=master cas.ticket.registry.jpa.dialect=org.hibernate.dialect.PostgreSQL95Dialect ``` @@ -86,7 +113,7 @@ cas.ticket.registry.jpa.dialect=org.hibernate.dialect.PostgreSQL95Dialect # In `pg_hba.conf` # TYPE DATABASE USER ADDRESS METHOD -host osf-cas longzechen 192.168.168.167/24 trust +host osf postgres 192.168.168.167/24 trust ``` ## Signing and Encryption Keys From a994072c36040fa5cc0490bf0a0b8420b0b12e03 Mon Sep 17 00:00:00 2001 From: Ostap Zherebetskyi Date: Thu, 26 Feb 2026 12:39:11 +0200 Subject: [PATCH 2/4] Update the documentation links --- README.md | 4 ++-- etc/cas/config/cas.properties | 28 +++++++++++------------ etc/cas/config/local/cas-local.properties | 28 +++++++++++------------ 3 files changed, 30 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index aceb05a4..72004296 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ OSF CAS is the centralized authentication and authorization service for the [OSF # Implementations -The implementation of OSF CAS is based on [Apereo CAS 6.2.8](https://github.com/apereo/cas/tree/v6.2.8) via [CAS Overlay Template 6.2.x](https://github.com/apereo/cas-overlay-template/tree/6.2). Refer to [CAS Documentation 6.2.x](https://apereo.github.io/cas/6.2.x/) for more details. +The implementation of OSF CAS is based on [Apereo CAS 6.2.8](https://github.com/apereo/cas/tree/v6.2.8) via [CAS Overlay Template 6.2.x](https://github.com/apereo/cas-overlay-template/tree/6.2). Refer to [CAS Documentation 6.2.x](https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/) for more details. ## Legacy Implementations @@ -95,7 +95,7 @@ cas.authn.osf-postgres.jpa.dialect=io.cos.cas.osf.hibernate.dialect.OsfPostgresD ## CAS DB -The implementation of OSF CAS uses the [JPA Ticket Registry](https://apereo.github.io/cas/6.2.x/ticketing/Configuring-Ticketing-Components.html#ticket-registry) for durable ticket storage and thus requires a relational database. Set up a `PostgreSQL@9.6` server and review [JPA Ticket Registry settings](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L127-L173). In most cases, only [Database connections](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L139-L143) need to be updated. Other JDBC and JPA settings can be adjusted if necessary. +The implementation of OSF CAS uses the [JPA Ticket Registry](https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/ticketing/Configuring-Ticketing-Components.md#ticket-registry) for durable ticket storage and thus requires a relational database. Set up a `PostgreSQL@9.6` server and review [JPA Ticket Registry settings](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L127-L173). In most cases, only [Database connections](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L139-L143) need to be updated. Other JDBC and JPA settings can be adjusted if necessary. Here is an example for local development. Use `192.168.168.167` to access host outside the docker container. Update `pg_hba.conf` to grant proper access permission depending on the setup. diff --git a/etc/cas/config/cas.properties b/etc/cas/config/cas.properties index 1c8bad4f..7296e826 100644 --- a/etc/cas/config/cas.properties +++ b/etc/cas/config/cas.properties @@ -25,8 +25,8 @@ cas.server.dev-mode.allow-force-http-error=${ALLOW_FORCE_HTTP_ERROR:false} ######################################################################################################################## # Throttling -# Configuration guide: https://apereo.github.io/cas/6.2.x/installation/Configuring-Authentication-Throttling.html -# Properties: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#authentication-throttling +# Configuration guide: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Configuring-Authentication-Throttling.md +# Properties: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#authentication-throttling ######################################################################################################################## # # Authentication Failure Throttling @@ -40,7 +40,7 @@ cas.authn.throttle.failure.range-seconds=1 ######################################################################################################################## # CAS Monitoring & Statistics Endpoints -# See: https://apereo.github.io/cas/6.2.x/monitoring/Monitoring-Statistics.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/monitoring/Monitoring-Statistics.md ######################################################################################################################## management.endpoints.web.exposure.include=health management.endpoint.health.enabled=true @@ -72,14 +72,14 @@ cas.authn.accept.users= ######################################################################################################################## # JSON Service Registry -# See: https://apereo.github.io/cas/6.2.x/services/JSON-Service-Management.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/services/JSON-Service-Management.md ######################################################################################################################## cas.serviceRegistry.json.location=file:/etc/cas/services ######################################################################################################################## ######################################################################################################################## # CAS Logout and Single Logout (SLO) -# https://apereo.github.io/cas/6.2.x/installation/Logout-Single-Signout.html +# https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Logout-Single-Signout.md ######################################################################################################################## # CAS Logout # @@ -130,7 +130,7 @@ cas.authn.osf-api.instn-authn-xsl-location=file:/etc/cas/institutions-auth.xsl ######################################################################################################################## # OSF PostgreSQL Authentication -# See: https://apereo.github.io/cas/6.2.x/installation/Configuring-Custom-Authentication.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Configuring-Custom-Authentication.md ######################################################################################################################## # Authentication settings # @@ -148,7 +148,7 @@ cas.authn.osf-postgres.jpa.dialect=${OSF_DB_HIBERNATE_DIALECT:io.cos.cas.osf.hib ######################################################################################################################## # JPA Ticket Registry -# See: https://apereo.github.io/cas/6.2.x/ticketing/JPA-Ticket-Registry.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/ticketing/JPA-Ticket-Registry.md ######################################################################################################################## # Global JDBC Settings # @@ -196,16 +196,16 @@ cas.ticket.registry.jpa.jpa-locking-timeout=PT1H ######################################################################################################################## # Signing and Encryption -# See: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties-Common.html#signing--encryption +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties-Common.md#signing--encryption ######################################################################################################################## # Spring Client Session -# See: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#spring-webflow-client-side-session +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#spring-webflow-client-side-session # cas.webflow.crypto.signing.key=${WEB_FLOW_SIGNING_KEY} cas.webflow.crypto.encryption.key=${WEB_FLOW_ENCRYPTION_KEY} # # Ticket Granting Cookie (TGC) -# See: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#signing--encryption-4 +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#signing--encryption-4 # cas.tgc.crypto.signing.key=${TGC_SIGNING_KEY} cas.tgc.crypto.encryption.key=${TGC_ENCRYPTION_KEY} @@ -213,7 +213,7 @@ cas.tgc.crypto.encryption.key=${TGC_ENCRYPTION_KEY} ######################################################################################################################## # Long-term Authentication: Ticket Granting Cookie (TGC) and Ticket Granting Ticket (TGT) -# See https://apereo.github.io/cas/6.2.x/installation/Configuring-LongTerm-Authentication.html +# See https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Configuring-LongTerm-Authentication.md ######################################################################################################################## # General Cookie Setting for Ticket Granting Cookie # @@ -242,7 +242,7 @@ cas.ticket.tgt.remember-me.time-to-kill-in-seconds=7776000 ######################################################################################################################## # Pac4j Delegated Authentication -# https://apereo.github.io/cas/6.2.x/integration/Delegate-Authentication.html +# https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/integration/Delegate-Authentication.md ######################################################################################################################## # General settings # @@ -275,8 +275,8 @@ cas.authn.pac4j.cas[0].callback-url-type=QUERY_PARAMETER ######################################################################################################################## # OAuth 2.0 Server -# Configuration guide: https://apereo.github.io/cas/6.2.x/installation/OAuth-OpenId-Authentication.html -# Properties: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#oauth2 +# Configuration guide: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/OAuth-OpenId-Authentication.md +# Properties: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#oauth2 ######################################################################################################################## # Authorization Code # diff --git a/etc/cas/config/local/cas-local.properties b/etc/cas/config/local/cas-local.properties index 6626573c..9347da1c 100644 --- a/etc/cas/config/local/cas-local.properties +++ b/etc/cas/config/local/cas-local.properties @@ -30,8 +30,8 @@ cas.server.dev-mode.allow-force-http-error=true ######################################################################################################################## # Throttling -# Configuration guide: https://apereo.github.io/cas/6.2.x/installation/Configuring-Authentication-Throttling.html -# Properties: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#authentication-throttling +# Configuration guide: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Configuring-Authentication-Throttling.md +# Properties: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#authentication-throttling ######################################################################################################################## # # Authentication Failure Throttling @@ -45,7 +45,7 @@ cas.authn.throttle.failure.range-seconds=1 ######################################################################################################################## # CAS Monitoring & Statistics Endpoints -# See: https://apereo.github.io/cas/6.2.x/monitoring/Monitoring-Statistics.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/monitoring/Monitoring-Statistics.md ######################################################################################################################## management.endpoints.web.exposure.include=health management.endpoint.health.enabled=true @@ -78,14 +78,14 @@ cas.authn.accept.users= ######################################################################################################################## # JSON Service Registry -# See: https://apereo.github.io/cas/6.2.x/services/JSON-Service-Management.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/services/JSON-Service-Management.md ######################################################################################################################## cas.serviceRegistry.json.location=file:/etc/cas/services ######################################################################################################################## ######################################################################################################################## # CAS Logout and Single Logout (SLO) -# https://apereo.github.io/cas/6.2.x/installation/Logout-Single-Signout.html +# https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Logout-Single-Signout.md ######################################################################################################################## # CAS Logout # @@ -136,7 +136,7 @@ cas.authn.osf-api.instn-authn-xsl-location=file:/etc/cas/config/instn-authn.xsl ######################################################################################################################## # OSF PostgreSQL Authentication -# See: https://apereo.github.io/cas/6.2.x/installation/Configuring-Custom-Authentication.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Configuring-Custom-Authentication.md ######################################################################################################################## # Authentication settings # @@ -154,7 +154,7 @@ cas.authn.osf-postgres.jpa.dialect=io.cos.cas.osf.hibernate.dialect.OsfPostgresD ######################################################################################################################## # JPA Ticket Registry -# See: https://apereo.github.io/cas/6.2.x/ticketing/JPA-Ticket-Registry.html +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/ticketing/JPA-Ticket-Registry.md ######################################################################################################################## # Global JDBC Settings # @@ -204,16 +204,16 @@ cas.ticket.registry.jpa.jpa-locking-timeout=PT1H ######################################################################################################################## # Signing and Encryption -# See: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties-Common.html#signing--encryption +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties-Common.md#signing--encryption ######################################################################################################################## # Spring Client Session -# See: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#spring-webflow-client-side-session +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#spring-webflow-client-side-session # cas.webflow.crypto.signing.key=changeme cas.webflow.crypto.encryption.key=changeme # # Ticket Granting Cookie (TGC) -# See: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#signing--encryption-4 +# See: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#signing--encryption-4 # cas.tgc.crypto.signing.key=changeme cas.tgc.crypto.encryption.key=changeme @@ -221,7 +221,7 @@ cas.tgc.crypto.encryption.key=changeme ######################################################################################################################## # Long-term Authentication: Ticket Granting Cookie (TGC) and Ticket Granting Ticket (TGT) -# See https://apereo.github.io/cas/6.2.x/installation/Configuring-LongTerm-Authentication.html +# See https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/Configuring-LongTerm-Authentication.md ######################################################################################################################## # General Cookie Setting for Ticket Granting Cookie # @@ -248,7 +248,7 @@ cas.ticket.tgt.remember-me.time-to-kill-in-seconds=7200 ######################################################################################################################## # Pac4j Delegated Authentication -# https://apereo.github.io/cas/6.2.x/integration/Delegate-Authentication.html +# https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/integration/Delegate-Authentication.md ######################################################################################################################## # General settings # @@ -287,8 +287,8 @@ cas.authn.pac4j.cas[1].callback-url-type=QUERY_PARAMETER ######################################################################################################################## # OAuth 2.0 Server -# Configuration guide: https://apereo.github.io/cas/6.2.x/installation/OAuth-OpenId-Authentication.html -# Properties: https://apereo.github.io/cas/6.2.x/configuration/Configuration-Properties.html#oauth2 +# Configuration guide: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/installation/OAuth-OpenId-Authentication.md +# Properties: https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/configuration/Configuration-Properties.md#oauth2 ######################################################################################################################## # Authorization Code # From 7e44f4124acd8884fd88ec343ec4aa6924568821 Mon Sep 17 00:00:00 2001 From: Ostap Zherebetskyi Date: Thu, 26 Feb 2026 12:40:56 +0200 Subject: [PATCH 3/4] Update README.md to simplify local development instructions --- README.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 72004296..0017fc8b 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ cas.authn.osf-postgres.jpa.dialect=io.cos.cas.osf.hibernate.dialect.OsfPostgresD The implementation of OSF CAS uses the [JPA Ticket Registry](https://github.com/apereo/cas/blob/6.2.x/docs/cas-server-documentation/ticketing/Configuring-Ticketing-Components.md#ticket-registry) for durable ticket storage and thus requires a relational database. Set up a `PostgreSQL@9.6` server and review [JPA Ticket Registry settings](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L127-L173). In most cases, only [Database connections](https://github.com/CenterForOpenScience/osf-cas/blob/d0a03b51c9b1ce7795a210223c1ce38d5b2742de/etc/cas/config/cas.properties#L139-L143) need to be updated. Other JDBC and JPA settings can be adjusted if necessary. -Here is an example for local development. Use `192.168.168.167` to access host outside the docker container. Update `pg_hba.conf` to grant proper access permission depending on the setup. +Here is an example for local development. Use `192.168.168.167` to access host outside the docker container. ```yaml # In `cas.properties` or `cas-local.properties` @@ -105,17 +105,10 @@ Here is an example for local development. Use `192.168.168.167` to access host o cas.ticket.registry.jpa.user=postgres cas.ticket.registry.jpa.password= cas.ticket.registry.jpa.driver-class=org.postgresql.Driver -cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:5432/osf?targetServerType=master +cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:5432/osf_cas?targetServerType=master cas.ticket.registry.jpa.dialect=org.hibernate.dialect.PostgreSQL95Dialect ``` -```yaml -# In `pg_hba.conf` - -# TYPE DATABASE USER ADDRESS METHOD -host osf postgres 192.168.168.167/24 trust -``` - ## Signing and Encryption Keys ### CAS Server From 0837b383005e587d98052c06dc27edaeddddf751 Mon Sep 17 00:00:00 2001 From: Longze Chen Date: Thu, 26 Feb 2026 09:53:20 -0500 Subject: [PATCH 4/4] Apply suggestion from @cslzchen --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0017fc8b..7ed04db4 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ Here is an example for local development. Use `192.168.168.167` to access host o cas.ticket.registry.jpa.user=postgres cas.ticket.registry.jpa.password= cas.ticket.registry.jpa.driver-class=org.postgresql.Driver -cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:5432/osf_cas?targetServerType=master +cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:5432/osf-cas?targetServerType=master cas.ticket.registry.jpa.dialect=org.hibernate.dialect.PostgreSQL95Dialect ```