Alfresco Content Services (ACS) is an Enterprise Content Management (ECM) system that’s used for document and case management, project collaboration, web content publishing, and compliant records management. The flexible compute, storage, and database services that Kubernetes offers make it an ideal platform for Content Services. This Helm chart presents an enterprise-grade Content Services configuration that you can adapt to virtually any scenario with the ability to scale up, down or out, depending on your use case.

Before starting a production installation make sure you are familiar with how to secure your installation.

The Helm chart in this repository supports deploying the Enterprise or Community Edition of Content Services.

The Enterprise configuration deploys the following system:

Considerations

Alfresco provides tested Helm charts as a “deployment template” for customers who want to take advantage of the container orchestration benefits of Kubernetes. These Helm charts are undergoing continual development and improvement, and shouldn’t be used “as is” for your production environments, but should help you save time and effort deploying Content Services for your organization.

The Helm charts in this repository provide a PostgreSQL database in a Docker container and don’t configure any logging. This design was chosen so that you can install them in a Kubernetes cluster without changes, and they’re flexible enough for adopting to your actual environment.

You should use these charts in your environment only as a starting point, and modify them so that Content Services integrates into your infrastructure. You typically want to remove the PostgreSQL container, and connect the cs-repository directly to your database (this might require custom images to get the required JDBC driver in the container).

Another typical change is the integration of your company-wide monitoring and logging tools.

Deployment options

For the best results, we recommend deploying Content Services to AWS EKS.

There are also several Helm examples that show you how to deploy with various configurations:

• Deploy with AWS Services (S3, RDS and MQ)
• Deploy with Alfresco Intelligence Services
• Enable access to Alfresco Search Services
• Enable Email Services
• Use a custom metadata keystore

Customize

To customize the Helm deployment, for example applying AMPs, we recommend following the best practice of creating your own custom Docker image(s). The following customization guidelines walk you through this process.

Any customizations (including major configuration changes) should be done inside the Docker image, resulting in the creation of a new image with a new tag. This approach allows changes to be tracked in the source code (Dockerfile) and rolling updates to the deployment in the Kubernetes cluster.

The Helm chart configuration customization should only include environment-specific changes (for example DB server connection properties) or altered Docker image names and tags. The configuration changes applied via --set will only be reflected in the configuration stored in Kubernetes cluster, a better approach would be to have those in source control i.e. maintain your own values files.

Creating custom Docker images

The Docker Compose customization guidelines provides a detailed example of how to apply an AMP in a custom image. There’s also a more advanced example of building a custom image with configuration.

Using custom Docker images

Once you’ve created your custom image, you can either change the default values in the appropriate values file in the helm/alfresco-content-services folder, or you can override the values via the --set command-line option during the install:

Code copied to clipboard.
helm install alfresco/alfresco-content-services --set repository.image.repository="yourRegistry" --set repository.image.tag="yourTag" --set share.image.repository="yourRegistry" --set share.image.tag="yourTag"

Helm deployment with AWS EKS

This section describes how to deploy Content Services (ACS) Enterprise or Community using Helm onto EKS.

Amazon’s EKS (Elastic Container Service for Kubernetes) makes it easy to deploy, manage, and scale containerized applications using Kubernetes on AWS. EKS runs the Kubernetes management infrastructure for you across multiple AWS availability zones to eliminate a single point of failure.

The Enterprise configuration will deploy the following system:

Prerequisites

• You’ve read the main acs-deployment project README prerequisites section
• You’ve read the main Helm README page
• You are proficient in AWS and Kubernetes

Set up an EKS cluster

Follow the AWS EKS Getting Started Guide to create a cluster and prepare your local machine to connect to the cluster. Use the Managed nodes - Linux option and specify a --node-type of at least m5.xlarge.

As we’ll be using Helm to deploy the Content Services chart, follow the Using Helm with EKS instructions to set up Helm on your local machine.

Optionally, to help troubleshoot issues with your cluster either follow the tutorial to deploy the Kubernetes Dashboard to your cluster or download and use the Lens application from your local machine.

Prepare the cluster for Content Services

Now we have an EKS cluster up and running, there are a few one time steps we need to perform to prepare the cluster for Content Services to be installed.

DNS

1. Create a hosted zone in Route53 using these steps if you don’t already have one available.

2. Create a public certificate for the hosted zone (created in step 1) in Certificate Manager using these steps if you don’t have one already available. Make a note of the certificate ARN for use later.

3. Create a file called external-dns.yaml with the text below (replace YOUR-DOMAIN-NAME with the domain name you created in step 1). This manifest defines a service account and a cluster role for managing DNS:

   Code copied to clipboard.
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: external-dns
    ---
    apiVersion: rbac.authorization.k8s.io/v1beta1
    kind: ClusterRole
    metadata:
      name: external-dns
    rules:
    - apiGroups: [""]
      resources: ["services","endpoints","pods"]
      verbs: ["get","watch","list"]
    - apiGroups: ["extensions"]
      resources: ["ingresses"]
      verbs: ["get","watch","list"]
    - apiGroups: [""]
      resources: ["nodes"]
      verbs: ["list","watch"]
    ---
    apiVersion: rbac.authorization.k8s.io/v1beta1
    kind: ClusterRoleBinding
    metadata:
      name: external-dns-viewer
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: external-dns
    subjects:
    - kind: ServiceAccount
      name: external-dns
      namespace: kube-system
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: external-dns
    spec:
      strategy:
        type: Recreate
      selector:
        matchLabels:
          app: external-dns
      template:
        metadata:
          labels:
            app: external-dns
        spec:
          serviceAccountName: external-dns
          containers:
          - name: external-dns
            image: registry.opensource.zalan.do/teapot/external-dns:latest
            args:
            - --source=service
            - --domain-filter=YOUR-DOMAIN-NAME
            - --provider=aws
            - --policy=sync
            - --aws-zone-type=public
            - --registry=txt
            - --txt-owner-id=acs-deployment
            - --log-level=debug
   

4. Use the kubectl command to deploy the external-dns service.

   Code copied to clipboard.
   kubectl apply -f external-dns.yaml -n kube-system
   

5. List node groups for your cluster and make note of nodegroup name YOUR-NODEGROUP (replace YOUR-CLUSTER-NAME with the name you gave your cluster).

   Code copied to clipboard.
   bash aws eks list-nodegroups --cluster-name YOUR-CLUSTER-NAME
   

6. Find the name of the role used by the nodes by running the following command (replace YOUR-CLUSTER-NAME with the name you gave your cluster and YOUR-NODEGROUP with your nodegroup name):

   Code copied to clipboard.
    aws eks describe-nodegroup --cluster-name YOUR-CLUSTER-NAME --nodegroup-name YOUR-NODEGROUP --query "nodegroup.nodeRole" --output text
   

7. In the IAM console find the role discovered in the previous step and attach the AmazonRoute53FullAccess managed policy as shown in the screenshot below:

   

File system

1. Create an Elastic File System in the VPC created by EKS using these steps ensuring a mount target is created in each subnet. Make a note of the File System ID (circled in the screenshot below):

   

2. Find the ID of the VPC created when your cluster was built (replace YOUR-CLUSTER-NAME with the name you gave your cluster):

   Code copied to clipboard.
    aws eks describe-cluster --name YOUR-CLUSTER-NAME --query "cluster.resourcesVpcConfig.vpcId" --output text
   

3. Find the CIDR range of the VPC (replace VPC-ID with the ID retrieved in the previous step):

   Code copied to clipboard.
    aws ec2 describe-vpcs --vpc-ids VPC-ID --query "Vpcs[].CidrBlock" --output text
   

4. Go to the Security Groups section of the VPC Console and search for the VPC using the ID retrieved in step 2, as shown in the screenshot below:

   

5. Click on the default security group for the VPC (highlighted in the screenshot above) and add an inbound rule for NFS traffic from the VPC CIDR range as shown in the screenshot below:

   

6. Deploy an NFS Client Provisioner with Helm using the following commands (replace EFS-DNS-NAME with the string FILE-SYSTEM-ID.efs.AWS-REGION.amazonaws.com where the FILE-SYSTEM-ID is the ID retrieved in step 1 and AWS-REGION is the region you’re using, e.g. fs-72f5e4f1.efs.us-east-1.amazonaws.com):

   Code copied to clipboard.
    helm repo add stable https://kubernetes-charts.storage.googleapis.com
    helm install alfresco-nfs-provisioner stable/nfs-client-provisioner --set nfs.server="EFS-DNS-NAME" --set nfs.path="/" --set storageClass.name="nfs-client" --set storageClass.archiveOnDelete=false -n kube-system
   

Deploy Content Services

Now the EKS cluster is setup we can deploy Content Services.

Namespace

Namespaces in Kubernetes isolate workloads from each other. Create a namespace to host Content Services inside the cluster using the following command. We’ll then use the alfresco namespace throughout the rest of the tutorial:

Code copied to clipboard.
kubectl create namespace alfresco

Ingress

1. Create a file called ingress-rbac.yaml with the text below:

   Code copied to clipboard.
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: acs:psp
      namespace: alfresco
    rules:
    - apiGroups:
      - policy
      resourceNames:
      - kube-system
      resources:
      - podsecuritypolicies
      verbs:
      - use
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: acs:psp:default
      namespace: alfresco
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: acs:psp
    subjects:
    - kind: ServiceAccount
      name: default
      namespace: alfresco
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: acs:psp:acs-ingress
      namespace: alfresco
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: acs:psp
    subjects:
    - kind: ServiceAccount
      name: acs-ingress
      namespace: alfresco
   

2. Use the kubectl command to create the cluster roles required by the ingress service:

   Code copied to clipboard.
    kubectl apply -f ingress-rbac.yaml -n alfresco
   

3. Deploy the ingress (replace ACM_CERTIFICATE_ARN and YOUR-DOMAIN-NAME with the ARN of the certificate and hosted zone created earlier in the DNS section):

   Code copied to clipboard.
    helm install acs-ingress ingress-nginx/ingress-nginx --version=3.7.1\
    --set controller.scope.enabled=true \
    --set controller.scope.namespace=alfresco \
    --set rbac.create=true \
    --set controller.config."proxy-body-size"="100m" \
    --set controller.service.targetPorts.https=80 \
    --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-backend-protocol"="http" \
    --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-ssl-ports"="https" \
    --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-ssl-cert"="ACM_CERTIFICATE_ARN" \
    --set controller.service.annotations."external-dns\.alpha\.kubernetes\.io/hostname"="acs.YOUR-DOMAIN-NAME" \
    --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-ssl-negotiation-policy"="ELBSecurityPolicy-TLS-1-2-2017-01" \
    --set controller.publishService.enabled=true \
    --atomic \
    --namespace alfresco
   

   Note: The command will wait until the deployment is ready.

Docker registry secret

Create a docker registry secret to allow the protected images to be pulled from Quay.io by running the following command (replace YOUR-USERNAME and YOUR-PASSWORD with your credentials):

Code copied to clipboard.
kubectl create secret docker-registry quay-registry-secret --docker-server=quay.io --docker-username=YOUR-USERNAME --docker-password=YOUR-PASSWORD -n alfresco

Choose Content Services version

This repository allows you to either deploy a system using released stable artefacts or the latest in-progress development artefacts.

To use a released version of the Helm chart add the stable repository using the following command:

Code copied to clipboard.
helm repo add alfresco https://kubernetes-charts.alfresco.com/stable

Alternatively, to use the latest in-progress development version of the Helm chart add the incubator repository using the following command:

Code copied to clipboard.
helm repo add alfresco https://kubernetes-charts.alfresco.com/incubator

Now decide whether you want to install the latest version of Content Services (Enterprise or Community) or a previous version, and follow the steps in the relevant section below.

Latest Enterprise version

Deploy the latest version of Content Services by running the following command (replace YOUR-DOMAIN-NAME with the hosted zone you created earlier):

Code copied to clipboard.
helm install acs alfresco/alfresco-content-services \
--set externalPort="443" \
--set externalProtocol="https" \
--set externalHost="acs.YOUR-DOMAIN-NAME" \
--set persistence.enabled=true \
--set persistence.storageClass.enabled=true \
--set persistence.storageClass.name="nfs-client" \
--set global.alfrescoRegistryPullSecrets=quay-registry-secret \
--atomic \
--timeout 10m0s \
--namespace=alfresco

Note: The command will wait until the deployment is ready.

Previous Enterprise version

1. Download the version specific values file you require from the helm/alfresco-content-services folder.

2. Deploy the specific version of Content Services by running the following command (replace YOUR-DOMAIN-NAME with the hosted zone you created earlier, and MAJOR & MINOR with the appropriate values):

   Code copied to clipboard.
    helm install acs alfresco/alfresco-content-services \
    --values=MAJOR.MINOR.N_values.yaml \
    --set externalPort="443" \
    --set externalProtocol="https" \
    --set externalHost="acs.YOUR-DOMAIN-NAME" \
    --set persistence.enabled=true \
    --set persistence.storageClass.enabled=true \
    --set persistence.storageClass.name="nfs-client" \
    --set global.alfrescoRegistryPullSecrets=quay-registry-secret \
    --atomic \
    --timeout 10m0s \
    --namespace=alfresco
   

   Note: The command will wait until the deployment is ready.

Access

When the deployment is complete, you can access the following URLs. Replace YOUR-DOMAIN-NAME with the hosted zone you created earlier:

• Repository: https://acs.YOUR-DOMAIN-NAME/alfresco
• Alfresco Share: https://acs.YOUR-DOMAIN-NAME/share
• API Explorer: https://acs.YOUR-DOMAIN-NAME/api-explorer

Since you deployed Enterprise, you’ll also have access to:

• Alfresco Digital Workspace: https://acs.YOUR-DOMAIN-NAME/workspace/
• Alfresco Sync Service: https://acs.YOUR-DOMAIN-NAME/syncservice/healthcheck

If you’re running Content Services 7.4 (i.e. the latest version) and already have a valid license file for this version, you can apply it directly to the running system. Navigate to the Admin Console and apply your license:

• https://acs.YOUR-DOMAIN-NAME/alfresco/service/enterprise/admin/admin-license (this only applies for the Enterprise Download Trial)
• Default username and password is admin
• See Uploading a new license for more details

Configuration options

By default, this tutorial installs an out-of-the-box setup, however there are many configuration options shown in the table below. There are also several examples covering various use cases.

The following table lists the configurable parameters of the Content Services chart and their default values.

This deployment is also not fully secured by default. To learn about and apply further restrictions including pod security, network policies etc., see the EKS Best Practices for Security.

Troubleshooting

Here’s some help for diagnosing and resolving any issues you may encounter.

Kubernetes dashboard

The easiest way to troubleshoot issues on a Kubernetes deployment is to use the dashboard. Assuming you’ve deployed the dashboard in the cluster, you can use the following steps to explore your deployment:

1. Retrieve the service account token with the following command:

   Code copied to clipboard.
    kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}')
   

2. Run the kubectl proxy:

   Code copied to clipboard.
    kubectl proxy &
   

3. Open a browser and navigate to: http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/#/login

4. Select Token, enter the token retrieved in step 1, and click Sign in.

5. Select alfresco from the Namespace menu, click Pods, and then the pod name.

   To view the logs, press the Menu icon in the toolbar as highlighted below:

   

Port-forwarding to a pod

This approach allows you to connect to a specific application in the cluster. See the Kubernetes documentation for details.

You can access any component of the deployment that’s not exposed via ingress rules in this way, for example Alfresco Search Services, DB or individual transformers.

View log files via command-line

You can view log files for individual pods from the command-line using the kubectl utility.

Retrieve the list of pods in the alfresco namespace:

Code copied to clipboard.
kubectl get pods -n alfresco

Retrieve the logs for a pod using the following command (replace the pod name accordingly):

Code copied to clipboard.
kubectl logs acs-alfresco-cs-repository-69545958df-6wzl6 -n alfresco

To continually follow the log file for a pod, use the -f option:

Code copied to clipboard.
kubectl logs -f acs-alfresco-cs-repository-69545958df-6wzl6 -n alfresco

Change log levels

You can change the log levels for the specific Java packages in the content-repository via the Admin Console. Use the following URL to access it: https://<host>/alfresco/service/enterprise/admin/admin-log-settings

Note: Changes are only applied to the content-repository node from which the Admin Console is launched.

• You can change the log levels by modifying log4j2.properties in the content-repository image and doing a rolling update to the deployment. In this case the settings will be applied system-wide. See the customization guidelines for more.
• The Content Services deployment doesn’t include any log aggregation tools. The logs generated by pods will be lost once the pods are terminated.

JMX dump

This tool allows you to download a ZIP file containing information useful for troubleshooting and supporting your system. Issue a GET request (Admin only) to: https://<host>/alfresco/service/api/admin/jmxdump.

Cleanup

1. Remove the acs and acs-ingress deployments:

   Code copied to clipboard.
     helm uninstall -n alfresco acs acs-ingress
   

2. Delete the Kubernetes namespace:

   Code copied to clipboard.
    kubectl delete namespace alfresco
   

3. Go to the EFS Console, select the file system we created earlier, and press the “Delete” button to remove the mount targets and file system.

4. Go to the IAM console and remove the AmazonRoute53FullAccess managed policy we added to the NodeInstanceRole in the File System section otherwise the cluster will fail to delete in the next step.

5. Finally, delete the EKS cluster (replace YOUR-CLUSTER-NAME with the name you gave your cluster):

   Code copied to clipboard.
    eksctl delete cluster --name YOUR-CLUSTER-NAME