# Upgrade

To set up a deployment, ESS provides various [Kustomize](https://github.com/kubernetes-sigs/kustomize) [overlays](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-overlays) These overlays can act as the base for major/minor upgrades as well as for the initial installation.

See also [Release Notes](https://docs.inrupt.com/ess/2.3/releases).

{% hint style="warning" %}
**Important**\
Inputs may change per versions. For example, a new input file may be added or new input may be required in an existing input file. Always review the contents of the **`inputs/`** folder when performing the installation/upgrades.
{% endhint %}

## Procedure

{% hint style="info" %}
**Note**\
Both the installation and the upgrade tutorials follow the Infrastructure as Code (IaC) practice for managing the system and assumes the ESS installation directory is under source control.

The tutorial illustrates the steps assuming GitHub as the source control system.
{% endhint %}

### Step 1: Prepare the Installation Directory

1. Go to your ESS installation directory.

   ```sh
   cd ${HOME}/ess
   ```
2. Checkout a new branch.
3. Remove all files in this branch to have an empty **`${HOME}/ess`** directory.

{% hint style="warning" %}
**Important**

Ensure that the directory is empty.
{% endhint %}

4. Login to Inrupt’s private Docker registry. When prompted for your password, enter your [entitlement token](https://docs.inrupt.com/ess/installation#entitlement-token) :

   ```sh
   docker login  --username <userid> docker.software.inrupt.com
   ```
5. Get the latest **`2.3`** version of the **`inrupt-kustomizer`** :

{% hint style="info" %}
ESS uses **three-element** version descriptors for its Kubernetes images, corresponding to the release versions (i.e., semantic versions of Major.Minor.Patch). As such, to get the latest version, you must use the specific patch version.
{% endhint %}

```sh
docker pull docker.software.inrupt.com/inrupt-kustomizer:2.3.6
```

6\. Initialize an empty installation directory with a base [overlay](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-overlays) for your environment:

{% hint style="warning" %}
**Important**\
If the directory is not empty, the **`inrupt-kustomizer`** does not attempt to initialize the directory with the base configuration files.
{% endhint %}

```sh
docker run -it -v ${HOME}/ess:/kustomize docker.software.inrupt.com/inrupt-kustomizer:2.3.6
```

Follow the prompts to install the base overlay for your upgrade version, same as the initial installation.

### Step 2: Update Inputs and Build

{% hint style="warning" %}
Important\
Inputs may change per versions. For example, a new input file may be added or new input may be required in an existing input file. Always review the contents of the **`inputs/`** folder when performing the installation/upgrades.
{% endhint %}

During the initialization, Inrupt generates a **`readme.txt`** file in the installation directory. The file provides instructions on updating inputs for your deployment and building the deployment file.

1. Go to the installation directory.

   ```sh
   cd ${HOME}/ess
   ```
2. Using the instructions in the **`readme.txt`** file, update the inputs in the base overlay for your deployment.

{% hint style="danger" %}
**Warning**

**CRITICAL SECURITY REQUIREMENT**

**NEVER commit files containing secrets such as** **`.env` or `JWT`** **to version control.** These files must be managed securely.

As part of updating the inputs for your deployment:

1. **Review** the template secret files
2. **Set strong secrets** for the values, such as strong passwords
3. **Store the secret securely** outside your repository using one of these methods:
   * Cloud secrets management service
   * Enterprise secrets vault solution
   * Kubernetes Secrets with encryption at rest
   * Secure file system with restricted access (development only)
4. **Configure your deployment** to retrieve credentials from your secure storage at runtime
5. **Add the secrets files to your `.gitignore` file immediately**
   {% endhint %}

{% hint style="warning" %}
**Important**\
Inputs may change per versions. For example, a new input file may be added or new input may be required in an existing input file. Review the contents of your **`inputs/`** folder for your installation/upgrades.
{% endhint %}

{% hint style="warning" %}
**Kafka Message Encryption**\
\
ESS’ services communicate with each other by sending messages through Kafka.

By default, Inrupt enables data encryption for all data that pass through the Kafka messaging system.

You **MUST** set the data encryption key values to a strong password.

For more information on the Kafka configurations, see [ESS’ Kafka Configuration](https://docs.inrupt.com/ess/2.3/services/appendix/appendix-kafka-configuration).
{% endhint %}

3. After updating the inputs, build the deployment file per the instructions in the **`readme.txt`** file.
4. Commit all changes in the directory to source control.

{% hint style="warning" %}
**Important**\
Ensure that the repo is *private*.
{% endhint %}

### Step 3: Optional. Customize Your Deployment Configuration

Optionally, you can further customize your ESS deployment using Kustomize [overlays](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-overlays), such as to use certificates from an official Certificate Authority (CA).

{% hint style="info" %}
Note\
You can opt to customize after setting up a base deployment.
{% endhint %}

For examples on customizing your deployment with overlays, see [Customize ESS](https://docs.inrupt.com/ess/2.3/installation/customize-configurations) .

### Step 4: Deploy

After you have built the deployment file, you can deploy.

1. If not already, go to the installation directory:

   ```sh
   cd ${HOME}/ess
   ```
2. Deploy to your Kubernetes environment:

   ```sh
   kubectl apply -f kustomized.yaml
   ```

{% hint style="info" %}
**Tip**\
The deploy operation is idempotent. If the deploy operation does not complete successfully, you can safely retry the operation.
{% endhint %}

{% hint style="danger" %}
**Warning: Self-signed Certificates**\
The provided base overlays create self-signed certificates. These self-signed certificates are for **development purposes only**. In production, ESS should be run with certificates from an official Certificate Authority (CA). For an example of how you can customize your deployment to use your production certificates, see [Use Official Certificate Authority](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-security/use-production-lets-encrypt).
{% endhint %}

3\. You can view the ESS components and services that are running:

```
kubectl -n ess get all
```

4\. **For local standalone deployments** , add the ESS service domains to the **`/etc/hosts`** file on your local machine.

<details>

<summary>The following steps are specific to Linux operating system.</summary>

1. Get your local Kubernetes cluster IP address:

   ```sh
   K8_IP=$(kubectl get nodes -o jsonpath="{.items[*].status.addresses[?(@.type=='InternalIP')].address}")
   ```
2. Get a list of the ESS service domains:

   ```sh
   ESS_DOMAINS=$(grep "host: " kustomized.yaml | awk '{print $3}' | sort -u | tr -d '\r' | tr '\n' ' ')
   ```
3. Backup your **`/etc/hosts`** file:

   ```sh
   sudo cp /etc/hosts /etc/hosts.bak
   ```
4. Update the **`/etc/hosts`**:

   ```sh
   sudo sed -n -e '/# ESS-DOMAINS-BEGIN/,/# ESS-DOMAINS-END/!p' -e '$a# ESS-DOMAINS-BEGIN\n'"$K8_IP $ESS_DOMAINS"'\n# ESS-DOMAINS-END' -i /etc/hosts
   ```

</details>

5. To verify, go to **`https://start.{ESS DOMAIN}/`**.