Missing important keystore configuration steps in ACS 7 in Windows manual full distribution zip deployment documentation
Description
Request
Please fix our ACS 7 - Install with zip documentation to include these important missing steps.
> https://docs.alfresco.com/content-services/latest/install/zip/tomcat/ - step 2
Step to reproduce
Try to perform a manual ACS 7 deployment on Windows Server 2019 strictly following ACS 7 - Install with zip documentation (ref: https://docs.alfresco.com/content-services/latest/install/zip/tomcat/)
dir.root=C:/acs7/alf_data
dir.keystore=${dir.root}/keystore
and try to startup with the default alf_data/keystore/metdata-keystore/keystore file which come OOTB, in reference to the downloaded alfresco-content-services-distribution-7.0.0.zip > extracted alfresco-content-services-distribution-7.0.0 > keystore > metadata-keystore , there are two files : (a) keystore and (b) keystore-passwords.properties encountered keystore issue on initial startup.
The initial startup always failed with:
This can be easily reproduced when following the "Install with zip" documentation steps https://docs.alfresco.com/content-services/latest/install/zip/tomcat/
After investigation, we determined the documentation has missing installation steps, related to specifying alfresco keystore location and file.
Validated Workaround:
Below are the missing steps which need to be done to avoid the error and pick up the default keystores:
Step 1. Move the default keystore files from:
downloaded alfresco-content-services-distribution-7.0.0.zip > extracted alfresco-content-services-distribution-7.0.0 > keystore > metadata-keystore , there are two files : (a) keystore and (b) keystore-passwords.properties
to my sample ACS 7’s keystore directory path:
C:/acs7/alf_data/keystore/metadata-keystore/keystore
C:/acs7/alf_data/keystore/metadata-keystore/keystore-passwords.properties
Step 2. To configure ACS 7 Tomcat 9 to use this default keystore file, open <tomcat 9_install_home_directory>/bin/catalina.bat in a text editor application to edit.
Step 3. Add this line into catalina.bat (I prefer to add mine right under 'set JAVA_OPTS=' lines)
set “JAVA_TOOL_OPTIONS=-Dencryption.keystore.type=JCEKS -Dencryption.cipherAlgorithm=DESede/CBC/PKCS5Padding -Dencryption.keyAlgorithm=DESede {color:red}-Dencryption.keystore.location=C:/acs7/alf_data/keystore/metadata-keystore/keystore{color} -Dmetadata-keystore.password=mp6yc0UD9e -Dmetadata-keystore.aliases=metadata -Dmetadata-keystore.metadata.password=oKIWzVdEdA -Dmetadata-keystore.metadata.algorithm=DESede”
Note: Make sure to replace and set -Dencryption.keystore.location=<your own keystore file location> as in step #1
Step 4. Then, you can run the /tomcat/bin/startup.bat to start your ACS tomcat 9 (activemq already running). Assuming all other configuration setting is configured properly, your ACS 7.0 should then startup without the previous keystore error.
Investigation findings
These missing steps seem to be related to the new keystore configuration implementation nows required to be set/read as JAVA properties/parameter. (Ref: https://docs.alfresco.com/content-services/latest/admin/security/#alfresco-keystore-configuration). However, since it is not being mentioned in our manual install as zip deployment documentation, this is causing a big confusion/frustration among our customers.
Environment
ACS 7.0, Windows Server 2019