Skip to content

Commit

Permalink
OPSEXP-1821 Update helm docs with Rancher Desktop deployment (#1003)
Browse files Browse the repository at this point in the history
  • Loading branch information
@slohe1
slohe1 authored Sep 11, 2023
1 parent 102b426 commit f80181c
Showing 1 changed file with 34 additions and 39 deletions.
73 changes: 34 additions & 39 deletions docs/helm/docker-desktop-deployment.md → docs/helm/desktop-deployment.md
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,54 @@
# Alfresco Content Services Helm Deployment with Docker For Desktop
# Alfresco Content Services Helm Deployment on local machines

This page describes how to deploy Alfresco Content Services (ACS) Enterprise or Community using [Helm](https://helm.sh) onto [Docker for Desktop](https://docs.docker.com/desktop/).
This page describes how to deploy Alfresco Content Services (ACS) Enterprise or Community using [Helm](https://helm.sh) onto [Rancher Desktop](https://rancherdesktop.io/) and [Docker for Desktop](https://docs.docker.com/desktop/).

## Prerequisites

- You've read the projects [main README](/README.md#prerequisites) prerequisites section
- You've read the [main Helm README](./README.md) page
- You are proficient in Kubernetes
- A machine with at least 16GB memory
- [Docker for Desktop](https://docs.docker.com/desktop/) for container management installed
- Latest version of [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) is installed
- Latest version of [Helm](https://helm.sh/docs/intro/install) is installed
- Having installed either of:
- [Rancher for Desktop](https://rancherdesktop.io/). Includes kubectl and Helm, ready to use right after installation.
- [Docker for Desktop](https://docs.docker.com/desktop/). Requires separate install of kubectl and Helm.

The following instructions are also applicable to [Rancher Desktop](https://rancherdesktop.io/) users. Rancher desktop will provide `kubectl` and `helm` out of the box. it is open source but less mature than Docker desktop.

## Configure Docker for Desktop

In order to deploy onto Docker for Desktop we need to configure it with as much CPU and memory as possible on the "Resources" tab in Docker for Desktop's preferences pane as shown in the screenshot below. Similar resource requirement apply to Rancher Desktop.
### Rancher Desktop specific configuration

![Resources](./diagrams/dfd-resources.png)
Uncheck `Enable Traefik` from the `Kubernetes Settings` page to disable the default ingress controller. You may need to exit and restart Rancher Desktop for the change to take effect. Ref: [Setup NGINX Ingress Controller](https://docs.rancherdesktop.io/how-to-guides/setup-NGINX-Ingress-Controller)

### Docker for Desktop specific configuration
### Docker Desktop specific configuration

To deploy the Helm charts Kubernetes needs to be enabled, this can be done from the "Kubernetes" tab, as shown in the screenshot below. Press the "Apply & Restart" button to confirm.
On top of the Docker desktop [Prerequisites](./desktop-deployment.md#Prerequisites), it is essential to install the latest version of [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) & [Helm](https://helm.sh/docs/intro/install).

![k8s Enabled](./diagrams/dfd-k8s-enabled.png)
After the installation of Docker Desktop, the following configurations should be adjusted within Docker Desktop settings.

### Rancher Desktop specific configuration
- `Settings > Resources > Advanced > CPUs:8, Memory: 16GB, Swap: 1GB`
- `Settings > kubernetes > Enable Kubernetes`

Uncheck `Enable Traefik` from the `Kubernetes Settings` page to disable Traefik. You may need to exit and restart Rancher Desktop for the change to take effect. Ref: [Setup NGINX Ingress Controller](https://docs.rancherdesktop.io/how-to-guides/setup-NGINX-Ingress-Controller)
After changing the necessary settings `Apply and restart` the docker desktop.

## Deploy
## Deployment

Once Docker for Desktop is running follow the steps in the following sections to deploy ACS (Enterprise or Community) to your local machine.
Please proceed to execute the instructions detailed in the following sections for the installation of ACS (Enterprise or Community edition) on your local system.

### Namespace

Namespaces in Kubernetes isolate workloads from each other, create a namespace to host ACS inside the cluster using the following command (we'll then use the `alfresco` namepsace throughout the rest of the tutorial):
To establish an isolated environment for ACS within the Kubernetes cluster, initiate the creation of a Kubernetes namespace using the provided command. Throughout the subsequent sections of this tutorial, we will consistently refer to this namespace as 'alfresco'

```bash
kubectl create namespace alfresco
```

### Ingress

Add the chart repository using the following command:
Add the ingress-nginx chart repository:

```bash
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
```

Deploy an ingress controller into the alfresco namespace using the command below:
Install an ingress-nginx controller within the 'alfresco' namespace:

```bash
helm install acs-ingress ingress-nginx/ingress-nginx --version=4.4.0 \
Expand All @@ -68,33 +65,31 @@ helm install acs-ingress ingress-nginx/ingress-nginx --version=4.4.0 \
# Verify NGINX is up and running
kubectl get pods --namespace alfresco

NAME READY STATUS RESTARTS AGE
acs-ingress-ingress-nginx-controller-77b76b95f7-hf9hq 1/1 Running 0 2m55s
NAME READY STATUS RESTARTS AGE
acs-ingress-ingress-nginx-controller-5647c976f-f7b6q 1/1 Running 0 98m

# Verify expose localhost:80
kubectl get svc --namespace alfresco

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
acs-ingress-ingress-nginx-controller-admission ClusterIP 10.43.244.72 <none> 443/TCP 69m
acs-ingress-ingress-nginx-controller LoadBalancer 10.43.182.81 192.168.1.146 80:31155/TCP,443:32209/TCP 69m
acs-ingress-ingress-nginx-controller-admission ClusterIP 10.43.42.230 <none> 443/TCP 98m
acs-ingress-ingress-nginx-controller LoadBalancer 10.43.90.117 192.168.29.69 80:31363/TCP,443:30980/TCP 98m
```

### ACS

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

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

```bash
helm repo add alfresco https://kubernetes-charts.alfresco.com/stable
helm repo update
```

Now decide whether you want to install the Community or Enterprise edition and follow the steps in the relevant section below.

#### Community
#### Community localhost deployment

To install the latest version of Community we need to use the [community_values.yaml file](../../helm/alfresco-content-services). Once downloaded execute the command below to deploy.
To install the latest version of Community we need to download the [community_values.yaml file](../../helm/alfresco-content-services). Once downloaded, execute the following to initiate the deployment.

```bash
helm install acs alfresco/alfresco-content-services \
Expand All @@ -109,8 +104,8 @@ helm install acs alfresco/alfresco-content-services \
#### Enterprise localhost deployment

See the [registry authentication](registry-authentication.md) page to configure
credentials to access the Alfresco Enterprise registry.
ACS enterprise version needs to pull container images from private image repositories.
To configure credentials for accessing the Alfresco Enterprise registry, please review the information provided in the [registry authentication](registry-authentication.md)

The Enterprise Helm deployment is intended for a Cloud based Kubernetes cluster
and therefore requires a large amount of resources out-of-the-box. To reduce the
Expand All @@ -123,7 +118,7 @@ To install the Enterprise on localhost we need to use the local-dev-values.yaml
curl -fO https://raw.githubusercontent.com/Alfresco/acs-deployment/master/docs/helm/values/local-dev-values.yaml
```

Once downloaded execute the command below to deploy.
Once downloaded, execute the following to initiate the deployment.

```bash
helm install acs alfresco/alfresco-content-services \
Expand All @@ -134,16 +129,16 @@ helm install acs alfresco/alfresco-content-services \
--namespace alfresco
```

> NOTE: The command will wait until the deployment is ready so please be patient. See below for [troubleshooting](./docker-desktop-deployment.md#troubleshooting) tips.
> NOTE: The command will wait until the deployment is ready so please be patient. See below for [troubleshooting](#troubleshooting) tips.
The command above installs the latest version of ACS Enterprise.
The `helm` command above installs the most current released version of ACS Enterprise.

#### Enterprise deployment for previous versions

To deploy a previous version of ACS Enterprise follow the steps below.

1. Download the version specific values file you require from [this folder](../../helm/alfresco-content-services)
2. Deploy the specific version of ACS by running the following command:
2. Deploying the specific version of ACS can be achieved by executing the following:

```bash
helm install acs alfresco/alfresco-content-services \
Expand Down Expand Up @@ -185,11 +180,11 @@ If you deployed Enterprise you'll also have access to:

## Troubleshooting

If your deployment fails it's most likely to be caused by resource limitations, please refer to the sections below for more information. Please also consult the [Helm Troubleshooting section](./README.md#Troubleshooting) for more generic troubleshooting tips and tricks.
In the event of a deployment failure, it is important to recognize that resource constraints are a common underlying cause. For further insights and guidance. Additionally, you can find more comprehensive troubleshooting advice in the [Helm Troubleshooting section](./README.md#Troubleshooting)

### Lack Of Resources

The most common reason for deployment failures with Docker for Desktop is lack of memory or disk space. Check the "Resources" tab in Docker for Desktop's preferences pane, increase the allocation if you can and re-try.
One of the most prevalent causes of deployment failures is insufficient memory or CPU resources. It is imperative to ensure that an adequate amount of resources is allocated to prevent deployment failures.

To save the deployment of two more pods you can also try disabling the Sync Service, to do that provide the additional `--set` option below with your helm install command:

Expand Down

0 comments on commit f80181c

Please sign in to comment.