[ENG-10237] Update CAS Set-up guide

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
 
@@ -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.
@@ -68,27 +95,20 @@ 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. 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.
 
 ```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-cas?targetServerType=master
 cas.ticket.registry.jpa.dialect=org.hibernate.dialect.PostgreSQL95Dialect
 ```
 
-```yaml
-# In `pg_hba.conf`
-
-# TYPE  DATABASE        USER            ADDRESS                 METHOD
-host    osf-cas         longzechen      192.168.168.167/24      trust
-```
-
 ## Signing and Encryption Keys
 
 ### CAS Server

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,24 +196,24 @@ 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}
 ########################################################################################################################
 
 ########################################################################################################################
 # 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
 #

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,24 +204,24 @@ 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
 ########################################################################################################################
 
 ########################################################################################################################
 # 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
 #