The Alfresco Digital Business Platform can be deployed to different environments such as AWS or locally.
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.
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.
Initialize the Helm Tiller:
helm init
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.
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.
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.
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.
helm repo add alfresco-incubator https://kubernetes-charts.alfresco.com/incubator
export ELB_CNAME="YourDesiredCname.YourRoute53DnsZone"
#example export ELB_CNAME="alfresco.example.com"
# Remember to use https here if you have a trusted certificate set on the ingress
helm install alfresco-incubator/alfresco-dbp \
--set alfresco-infrastructure.persistence.efs.enabled=true \
--set alfresco-infrastructure.persistence.efs.dns="$NFSSERVER" \
--set alfresco-infrastructure.alfresco-identity-service.client.alfresco.redirectUris=['\"'http://$ELB_CNAME*'"\'] \
--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
If you are using https
you should include the following setting in your helm install command:
--set alfresco-content-services.externalProtocol="https" \
If you want to include multiple uris for alfresco client redirect uris check this guide.
export DBPRELEASE=littering-lizzard
export ELBADDRESS=$(kubectl get services $DBPRELEASE-nginx-ingress-controller --namespace=$DESIREDNAMESPACE -o jsonpath={.status.loadBalancer.ingress[0].hostname})
echo $ELBADDRESS
- 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.
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
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.
Component | Recommended version | Getting Started Guide |
---|---|---|
Homebrew | 1.7.6 | https://brew.sh/ |
You can download the installer from: https://www.docker.com/products/docker-desktop
In the 'Kubernetes' tab of the Docker preferences, click the 'Enable Kubernetes' checkbox.
In the Advanced tab of the Docker preferences, set 'CPUs' to 4.
While Alfresco Digital Business Platform installs and runs with only 8 GiB allocated to Docker, for better performance we recommend that 'Memory' value be set slightly higher, to at least 10 - 12 GiB (depending on the size of RAM in your workstation).
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
brew update; brew install kubernetes-helm
helm init
helm repo add alfresco-incubator https://kubernetes-charts.alfresco.com/incubator
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.
See the Anaxes Shipyard documentation on secrets.
Note: You can reuse the secrets.yaml file from charts/incubator directory.
If you have a valid Alfresco Process Services license, you can apply it at deployment time
by creating a secret called licenseaps
from your license file:
kubectl create secret generic licenseaps --from-file=./activiti.lic --namespace=$DESIREDNAMESPACE
This step is optional. If you choose not to deploy the license this way, Alfresco Process Services will start up in read-only mode and you will need to apply it manually (see Notes below).
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-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"
kubectl get pods
Note: When checking status, your pods should be READY 1/1
and STATUS Running
You can access DBP components at the following URLs:
- http://localhost-k8s/alfresco
- http://localhost-k8s/share
- http://localhost-k8s/digital-workspace/
- http://localhost-k8s/activiti-app
- http://localhost-k8s/activiti-admin
- http://localhost-k8s/auth/
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 Process Services REST Endpoint' 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.
helm ls
Use the name of the DBP release found above as DBPRELEASE
helm delete --purge <DBPRELEASE>
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.
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
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
Error: Invalid parameter: redirect_uri
After deploying the DBP, when accesing one of the applications, for example Process Services, if you receive the error message We're sorry Invalid parameter: redirect_uri, the redirectUris
parameter provided for deployment is invalid. Make sure the alfresco-infrastructure.alfresco-identity-service.client.alfresco.redirectUris
parameter has a valid value when installing the chart. For more details on how to configure it, check this guide.