This post walks through the steps required to integrate custom code generated using the Alfresco SDK with our custom helm subchart. The steps shown in this article are used to run Alfresco Content Services (ACS) in a local kubernetes cluster like Docker Desktop. This article assumes you have read the previous articles in this series:
- Getting Started with Alfresco and Kubernetes: The Beginning,
- Getting Started with Alfresco and Kubernetes: Running Alfresco Content Services (Enterprise) in Docker Desktop
- Getting Started with Alfresco and Kubernetes: Custom Helm Chart to Create Persistent Storage.
We will be using Alfresco SDK 4.1.0 to create ACS repository and Share customizations. We will include these customizations to the helm sub chart project https://github.com/ziaconsulting/demo-helm-acs/tree/v1.0. This will allow us to include our Alfresco repo & share customizations as part of the ACS deployment.
The commands shown in this blog have been tested on my Docker Desktop Kubernetes cluster that is deployed on macOS Catalina. The helm subchart with the SDK integration that is created using the steps shown below can be viewed at https://github.com/ziaconsulting/demo-helm-acs/tree/v2.0.
Create an ACS SDK project
We assume you have all the necessary maven configurations to install an Alfresco SDK 4.1.x project that is compatible with ACS 6.2.x. More details on Alfresco SDK 4.1.x can be found at https://github.com/Alfresco/alfresco-sdk/blob/master/docs/README.md.
Before you create a new SDK project, we will clone https://github.com/ziaconsulting/demo-helm-acs/tree/v1.0 and create a new SDK project inside this project.
$ git clone -b v1.0 https://github.com/ziaconsulting/demo-helm-acs.git $ rm -rf demo-helm-acs/.git/ # Remove repo references to use in your env $ cd demo-helm-acs
All the commands shown below are run in the demo-helm-acs folder. The Alfresco SDK project is generated using the below command.
$ mvn archetype:generate -Dfilter=org.alfresco:
For this article, I used the alfresco-allinone-archetype archetype using SDK version 4.1.0 with groupId and artifactId set to com.zia and zia-custom respectively. The SDK project that is generated will automatically generate a sample helloworld webscript. We can use this webscript to validate that the SDK project is correctly installed later.
In my environment, the generated projects parent pom.xml contains a lot of empty spaces. I use the below command to clear out the empty lines to make it easier to read.
# This step can be skipped $ sed -i '' '/^[[:space:]]*$/d' zia-custom/pom.xml
I want to update the generated project to use the Alfresco Enterprise bits. More details on this can be found in https://github.com/Alfresco/alfresco-sdk/tree/sdk-4.1/docs/advanced-topics/working-with-enterprise. For our demo project, I used the below command to update the pom.xml to generate customizations for Alfresco Enterprise.
$ sed -i '' -e 's/>acs-community-packaging</>acs-packaging</' \ -e 's/\/alfresco-content-repository-community</\/alfresco-content-repository</' \ -e 's/>6.2.0-ea</>6.2.0</' zia-custom/pom.xml
The generated code creates Dockerfiles for both the Alfresco repository and Share. The Dockerfile for the Alfresco repository includes a custom alfresco-global.properties file. This properties file assumes both the repository and share will be running in the localhost. Since this will not be correct in the kubernetes cluster, we will comment out the line that includes alfresco-global.properties in the Alfresco repository Dockerfile.
$ sed -i '' '/COPY alfresco-global.properties/ s/^/#/' \ zia-custom/zia-custom-platform-docker/src/main/docker/Dockerfile
The Dockerfile for Alfresco Share includes a custom share-config-custom.xml file. This file has a placeholder ${acs.host} that will be populated from the parent pom.xml. This SDK generated name will not be correct in the kubernetes cluster. Hence, we will comment out the line that includes share-config-custom.xml in the Alfresco share Dockerfile.
$ sed -i '' '/COPY share-config-custom.xml/ s/^/#/' \ zia-custom/zia-custom-share-docker/src/main/docker/Dockerfile
The SDK project that is generated is set up to spin up using docker-compose and not kubernetes. We can include certain config details in both alfresco-global.properties and share-config-custom.xml that does not use host, port and protocol details. For example, the default alfresco-global.properties file that is generated by the SDK has the following properties
alfresco.host=localhost alfresco.port=8080 alfresco.protocol=http
The helm chart gives us the option to specify the host, port and protocol details using the helm/zia-acs/values.yaml as shown below.
alfresco-content-services: externalProtocol: http externalHost: 127.0.0.1 externalPort: 80
More details on how these values defined above are used by the parent helm chart template can be viewed at https://github.com/Alfresco/acs-deployment/blob/3.0.3/helm/alfresco-content-services/templates/config-repository.yaml.
By default, Alfresco Enterprise will give 2 free trial days. To add your license to the SDK, add your Alfresco license file to the zia-custom/zia-custom-platform-docker/src/main/docker/license folder.
Build custom images
In this article, we will not be adding any additional code/configuration to the SDK project. But, we will add Javascript Console as a custom module. You will need to make updates to both the repository and share docker projects to inject the necessary amps.
In zia-custom/zia-custom-platform-docker/pom.xml, add the following repository dependency.
<!-- Javascript Console Repo AMP --> <dependency> <groupId>de.fmaul</groupId> <artifactId>javascript-console-repo</artifactId> <version>0.6</version> <type>amp</type> </dependency>
In zia-custom/zia-custom-share-docker/pom.xml, add the following Share dependency.
<!-- Javascript Console Share AMP --> <dependency> <groupId>de.fmaul</groupId> <artifactId>javascript-console-share</artifactId> <version>0.6</version> <type>amp</type> </dependency>
We will build the generated project and the docker images using the following commands.
$ mvn -f zia-custom/pom.xml clean package $ docker-compose -f zia-custom/target/classes/docker/docker-compose.yml \ build --no-cache
After the docker build is done, validate the docker images are present in your system.
Update Helm chart
In our custom helm chart, we want to use our custom SDK images instead of the default repository and share images. Update the helm/zia-acs/values.yaml to use our custom images as shown below.
alfresco-content-services:
repository:
replicaCount: 1
# This assumes you have a custom ACS Repo image in your local machine
image:
repository: alfresco-content-services-zia-custom
tag: development
pullPolicy: Never # Required - This image is only available locally
share:
replicaCount: 1
# This assumes you have a custom ACS Share image in your local machine
image:
repository: alfresco-share-zia-custom
tag: development
pullPolicy: Never # Required - This image is only available locally
The custom helm chart will now use our local SDK images. While this might be good for local development, we will need to push this image to a public/private docker registry to access them in multiple clusters. When using a public/private docker registry, the values.yaml will need to be updated with those details.
Install helm chart with customizations
The following command will spin up ACS 6.2.0 with our custom images. This command will use the helm chart updated at helm/zia-acs. This latest chart has not yet been published for other users to use. We can test this local chart by installing it using the below command.
$ helm install helm/zia-acs --name acs-vj \ --set global.alfrescoRegistryPullSecrets=quay-registry-zia-secret
When we are ready to share this chart, we will have to package the chart as a new version. Update helm/zia-acs/Chart.yaml with the updated version details.
apiVersion: v1
appVersion: "6.2.0"
description: A Helm chart for Kubernetes with Alfresco SDK customizations
name: zia-acs
version: 0.2.0
We will use the following command to package the updates as a new version of the helm chart.
$ helm package helm/zia-acs --version 0.2.0 --destination zia-acs-release
This will generate a new zia-acs-0.2.0.tgz file in the zia-acs-release folder. We are now ready to include the new version 0.2.0 to the helm chart index. The following command will update the zia-acs-release/index.yaml file to reference version 0.2.0.
$ helm repo index zia-acs-release --url \ https://ziaconsulting.github.io/demo-helm-acs/zia-acs-release
Push all your changes to your git repo that has been configured to host your custom helm charts.
To use the hosted helm charts, add the helm repo and run update to pull get the latest chart updates as shown below.
$ helm repo add zia-helm-release \ https://ziaconsulting.github.io/demo-helm-acs/zia-acs-release $ helm repo update
We can use the following command to get a list of all the versions of the helm charts available for use.
$ helm search -l zia-helm-release/zia-acs NAME CHART VERSION APP VERSION DESCRIPTION zia-helm-release/zia-acs 0.2.0 6.2.0 A Helm chart for Kubernetes with Alfresco SDK customizations zia-helm-release/zia-acs 0.1.0 1.0 A Helm chart for Kubernetes
To install the latest 0.2.0 version of the shared sub chart, you will use the below command.
$ helm install zia-helm-release/zia-acs --name acs-vj \ --version 0.2.0 \ --set global.alfrescoRegistryPullSecrets=quay-registry-zia-secret
Validation
To validate that alfresco is successfully running in the Kubernetes cluster, navigate to https://localhost/alfresco. We can check that our custom SDK project was successfully installed by running the below command. In the command, I assume the default username and password has not been updated.
$ curl -uadmin:admin https://localhost/alfresco/s/sample/helloworld Message: 'Hello from JS!' 'HelloFromJava'
We can also validate that the javascript console has been installed by navigating to the below url in the browser.
https://localhost/share/page/console/admin-console/javascript-console
Cleanup
You can clean up the helm install by using the below command. Warning: This command will remove all your charts.
$ helm delete $(helm list -aq) --purge
To specifically remove your chart, use the below command by passing your chart release name
$ helm delete acs-vj --purge
Conclusion
We’ve seen how to add alfresco SDK customizations using a subchart. In the next blog post, I will walk you through the steps required to use an external database and add custom alfresco-global.properties values using a volume as part of the custom Helm install. We want to use a volume because we want to have different properties in alfresco-global.properties for different environments using the same docker image. Until then, be sure to catch up on this series, or contact Zia to continue the conversation.