Alfresco Digital Business Platform Deployment

The Alfresco Digital Business Platform can be deployed to different environments such as AWS or locally.

Deploy to AWS
Deploy to Docker for Desktop - Mac

AWS

Prerequisites

The Alfresco Digital Business Platform Deployment requires:

Component	Recommended version	Getting Started Guide
Docker	17.0.9.1	https://docs.docker.com/
Kubernetes	1.8.4	https://kubernetes.io/docs/tutorials/kubernetes-basics/
Kubectl	1.8.4	https://kubernetes.io/docs/tasks/tools/install-kubectl/
Helm	2.8.2	https://docs.helm.sh/using_helm/#quickstart-guide
Kops	1.8.1	https://github.com/kubernetes/kops/blob/master/docs/aws.md

Any variation from these technologies and versions may affect the end result. If you do experience any issues please let us know through our Gitter channel.

Note: You do not need to clone this repo to deploy the dbp.

Kubernetes Cluster

For more information please check the Anaxes Shipyard documentation on running a cluster.

Resource requirements for AWS:

A VPC and cluster with 5 nodes. Each node should be a m4.xlarge EC2 instance.

Helm Tiller

Initialize the Helm Tiller:

helm init

K8s Cluster Namespace

As mentioned as part of the Anaxes Shipyard guidelines, you should deploy into a separate namespace in the cluster to avoid conflicts (create the namespace only if it does not already exist):

export DESIREDNAMESPACE=example
kubectl create namespace $DESIREDNAMESPACE

This environment variable will be used in the deployment steps.

Docker Registry Pull Secrets

See the Anaxes Shipyard documentation on secrets.

Note: You can reuse the secrets.yaml file from charts/incubator directory.

cd charts/incubator
cat ~/.docker/config.json | base64

Add the base64 string generated to .dockerconfigjson in secrets.yaml. The file should look similar to this:

apiVersion: v1
kind: Secret
metadata:
  name: quay-registry-secret
type: kubernetes.io/dockerconfigjson
data:
# Docker registries config json in base64 to do this just run - cat ~/.docker/config.json | base64
  .dockerconfigjson: ew0KCSJhdXRocyI6IHsNCgkJImh0dHBzOi8vcXVheS5pbyI6IHsNCgkJCSJhdXRoIjogImRHVnpkRHAwWlhOMD0iDQoJCX0sDQoJCSJxdWF5LmlvIjogew0KCQkJImF1dGgiOiAiZEdWemREcDBaWE4w550KCQl9DQoJfSwNCgkiSHR0cEhlYWRlcnMiOiB7DQoJCSJVc2VyLUFnZW50IjogIkRvY2tlci1DbGllbnQvMTcuMTIuMC1jZS1yYzMgKGRhcndpbikiDQoJfQ0KfQ==

Then run this command:

kubectl create -f secrets.yaml --namespace $DESIREDNAMESPACE

Note: Make sure the $DESIREDNAMESPACE variable has been set when the infrastructure chart was deployed so that the secret gets created in the same namespace.

Ingress Customization

For routing the components of the DBP deployment outside the k8s cluster we use nginx-ingress. For your deployment to function properly you must have a route53 DNSZone and you will need to create a route53 record set in the following steps.

For more options on configuring the ingress controller that is deployed through the alfresco-infrastructure chart, please check the Alfresco Infrastructure chart Readme.

Deployment

1. EFS Storage

Create an EFS storage on AWS and make sure it is in the same VPC as your cluster. Make sure you open inbound traffic in the security group to allow NFS traffic.

Save the name of the server ex:

export NFSSERVER=fs-d660549f.efs.us-east-1.amazonaws.com

Note! The Persistent volume created to store the data on the created EFS has the ReclaimPolicy set to Recycle. This means that by default, when you delete the release the saved data is deleted automatically.

To change this behaviour and keep the data you can set the alfresco-infrastructure.persistence.reclaimPolicy value to Retain. For more Information on Reclaim Policies checkout the official K8S documentation here -> https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaim-policy

We don't advise you to use the same EFS instance for persisting the data from multiple dbp deployments.

2. Add the Alfresco Helm repository to helm

helm repo add alfresco-incubator https://kubernetes-charts.alfresco.com/incubator

3. Define a variable for your Route53 entry that you will use for the deployment

export ELB_CNAME="YourDesiredCname.YourRoute53DnsZone"
#example export ELB_CNAME="alfresco.example.com"

4. Deploy the DBP

# Remember to use https here if you have a trusted certificate set on the ingress
helm install alfresco-incubator/alfresco-dbp \
--set alfresco-infrastructure.alfresco-api-gateway.keycloakURL="http://$ELB_CNAME/auth/" \
--set alfresco-infrastructure.persistence.efs.enabled=true \
--set alfresco-infrastructure.persistence.efs.dns="$NFSSERVER" \
--set alfresco-content-services.externalHost="$ELB_CNAME" \
--set alfresco-content-services.networkpolicysetting.enabled=false \
--set alfresco-content-services.repository.environment.IDENTITY_SERVICE_URI="http://$ELB_CNAME/auth" \
--set alfresco-process-services.processEngine.environment.IDENTITY_SERVICE_AUTH="http://$ELB_CNAME/auth" \
--namespace=$DESIREDNAMESPACE

You can either deploy the dbp fully or choose the components you need for your specific case. By default the dbp chart will deploy fully.

To disable specific components you can set the following values to false when deploying:

alfresco-content-services.enabled
alfresco-process-services.enabled
alfresco-sync-service.enabled
alfresco-infrastructure.nginx-ingress.enabled

Example: For disabling sync-service you will need to append the following subcommand to the helm install command:

--set alfresco-sync-service.enabled=false

5. Get the DBP release name from the previous command and set it as a variable:

export DBPRELEASE=littering-lizzard

6. Get ELB IP and copy it for linking the ELB in AWS Route53:

export ELBADDRESS=$(kubectl get services $DBPRELEASE-nginx-ingress-controller --namespace=$DESIREDNAMESPACE -o jsonpath={.status.loadBalancer.ingress[0].hostname})
echo $ELBADDRESS

7. Create a Route 53 Record Set in your Hosted Zone

Go to AWS Management Console and open the Route 53 console.
Click Hosted Zones in the left navigation panel, then Create Record Set.
In the Name field, enter your "$ELB_CNAME" defined in step 4.
In the Alias Target, select your ELB address ("$ELBADDRESS").
Click Create.

You may need to wait a couple of minutes before the record set propagates around the world.

8. Checkout the status of your DBP deployment:

Note: When checking status, your pods should be READY 1/1

helm status $DBPRELEASE

If you want to see the full list of values that have been applied to the deployment you can run:

helm get values -a $DBPRELEASE

9. Teardown:

helm delete --purge $DBPRELEASE
kubectl delete namespace $DESIREDNAMESPACE

Depending on your cluster type you should be able to also delete it if you want.

For more information on running and tearing down k8s environments, follow this guide.

Notes

Because some of our modules pass headers bigger than 4k we had to increase the default value of the proxy buffer size for nginx. We also enable the CORS header for the applications that need it through the Ingress Rule.

Docker for Desktop - Mac

Prerequisites

Component	Recommended version	Getting Started Guide
Homebrew	1.7.6	https://brew.sh/

Deployment

1. Install Docker for Desktop

You can download the installer from: https://www.docker.com/products/docker-desktop

2. Enable Kubernetes

In the 'Kubernetes' tab of the Docker preferences, click the 'Enable Kubernetes' checkbox.

3. Increase Memory and CPUs

In the Advanced tab of the Docker preferences, set 'CPUs' to 4 and 'Memory' to 8 GiB

4. Change/Verify Context

If you have previously deployed the DBP to AWS or minikube you will need to change/verify that the docker-for-desktop context is being used.

kubectl config current-context                 # Display the current context
kubectl config use-context docker-for-desktop  # Set the default context if needed

5. Install Helm Client

brew update; brew install kubernetes-helm

6. Initialize Helm Tiller (Server Component)

helm init

7. Add the Alfresco Incubator Helm Repository

helm repo add alfresco-incubator https://kubernetes-charts.alfresco.com/incubator

8. Add Local DNS

Add Local DNS Entry for Host Machine (needed for JWT issuer matching). Be sure to specify an active network interface. It is not always en0 as illustrated. You can use the command ifconfig -a to find an active interface.

sudo sh -c 'echo "`ipconfig getifaddr en0`       localhost-k8s" >> /etc/hosts'; cat /etc/hosts

Note: If your IP address changes you will need to update the /etc/hosts entry for localhost-k8s.

9. Deploy the DBP

The extended install command configures the hostnames, URLs and memory requirements needed to run in Docker for Desktop. It also configures the time for initiating the kubernetes probes to test if a service is available.

helm install alfresco-incubator/alfresco-dbp \
--set alfresco-infrastructure.alfresco-api-gateway.keycloakURL="http://localhost-k8s/auth/" \
--set alfresco-infrastructure.rabbitmq-ha.enabled=false \
--set alfresco-infrastructure.alfresco-activiti-cloud-registry.enabled=false \
--set alfresco-infrastructure.alfresco-api-gateway.enabled=false \
--set alfresco-content-services.externalHost="localhost-k8s" \
--set alfresco-content-services.networkpolicysetting.enabled=false \
--set alfresco-content-services.repository.environment.IDENTITY_SERVICE_URI="http://localhost-k8s/auth" \
--set alfresco-content-services.repository.replicaCount=1 \
--set alfresco-content-services.repository.livenessProbe.initialDelaySeconds=420 \
--set alfresco-content-services.pdfrenderer.livenessProbe.initialDelaySeconds=300 \
--set alfresco-content-services.libreoffice.livenessProbe.initialDelaySeconds=300 \
--set alfresco-content-services.imagemagick.livenessProbe.initialDelaySeconds=300 \
--set alfresco-content-services.share.livenessProbe.initialDelaySeconds=420 \
--set alfresco-content-services.repository.resources.requests.memory="2000Mi" \
--set alfresco-content-services.pdfrenderer.resources.requests.memory="500Mi" \
--set alfresco-content-services.imagemagick.resources.requests.memory="500Mi" \
--set alfresco-content-services.libreoffice.resources.requests.memory="500Mi" \
--set alfresco-content-services.share.resources.requests.memory="1000Mi" \
--set alfresco-content-services.postgresql.resources.requests.memory="500Mi" \
--set alfresco-process-services.processEngine.environment.IDENTITY_SERVICE_AUTH="http://localhost-k8s/auth" \
--set alfresco-process-services.processEngine.resources.requests.memory="1000Mi" \
--set alfresco-process-services.adminApp.resources.requests.memory="250Mi"

10. Check Deployment Status of DBP

kubectl get pods

Note: When checking status, your pods should be READY 1/1 and STATUS Running

11. Check DBP Components

You can access DBP components at the following URLs:

Notes:

As deployed, the activiti-app starts in read-only mode.
- Apply a license by uploading an Activiti license file after deployment.
As deployed, the activiti-admin app does not work because it is not configured with the correct server endpoint.
- To fix that, click 'Edit endpoint configuration' and then in the form enter http://localhost-k8s for the server address.
- Save the form and click 'Check Process Services REST endpoint' to see if it is valid.
The http://localhost-k8s/activiti-admin/solr endpoint is disabled by default.
- See https://github.com/Alfresco/acs-deployment/blob/master/docs/examples/search-external-access.md for more information.

12. Teardown:

helm ls

Use the name of the DBP release found above as DBPRELEASE

helm delete --purge <DBPRELEASE>

Notes

kubectl not found

In some cases, after installing Docker for Desktop and enabling Kubernetes, the kubectl command may not be found. Docker for Desktop also installs the command as kubectl.docker. We would recommend using this command over installing the kubernetes cli which may not match the version of kubernetes that Docker for Desktop is using.

K8s Cluster Namespace

If you are deploying multiple projects in your Docker for Desktop Kuberenetes Cluster you may find it useful to use namespaces to segment the projects.

To create a namespace

export DESIREDNAMESPACE=example
kubectl create namespace $DESIREDNAMESPACE

You can then use this environment variable DESIREDNAMESPACE in the deployment steps by appending --namespace $DESIREDNAMESPACE to the helm and kubectl commands.

You may also need to remove this namespace when you no longer need it.

kubectl delete namespace $DESIREDNAMESPACE

K8s Dashboard

You may find it helpful to see the Kubernetes resources visually which can be achieved by installing the Kubernetes Dashboard: https://github.com/kubernetes/dashboard/wiki/Installation

alex4u2nv/alfresco-dbp-deployment

Alfresco Digital Business Platform Deployment

AWS

Prerequisites

Kubernetes Cluster

Helm Tiller

K8s Cluster Namespace

Docker Registry Pull Secrets

Ingress Customization

Deployment

1. EFS Storage

2. Add the Alfresco Helm repository to helm

3. Define a variable for your Route53 entry that you will use for the deployment

4. Deploy the DBP

5. Get the DBP release name from the previous command and set it as a variable:

6. Get ELB IP and copy it for linking the ELB in AWS Route53:

7. Create a Route 53 Record Set in your Hosted Zone

8. Checkout the status of your DBP deployment:

9. Teardown:

Docker for Desktop - Mac

Prerequisites

Deployment

1. Install Docker for Desktop

2. Enable Kubernetes

3. Increase Memory and CPUs

4. Change/Verify Context

5. Install Helm Client

6. Initialize Helm Tiller (Server Component)

7. Add the Alfresco Incubator Helm Repository

8. Add Local DNS

9. Deploy the DBP

10. Check Deployment Status of DBP

11. Check DBP Components

12. Teardown:

Notes

kubectl not found

K8s Cluster Namespace

K8s Dashboard