# Prerequisites

## Provision Enabling Systems

At a minimum level, deployment of the Rierino platform requires specific enabling systems to be in place, such as a database for persistence. It is recommended that the following (or equivalent systems supported by Rierino) be deployed before starting the platform deployment: 

<details>

<summary>MongoDB</summary>

* [ ] Deploy a MongoDB instance or cluster, to be used as the main data system (alternative data systems can be used with different state managers)
* [ ] Enable replication on MongoDB if not already enabled, restart services and initiate replication which is required for redundancy as well as change data capture purposes

<pre class="language-yaml"><code class="lang-yaml"><a data-footnote-ref href="#user-content-fn-1">replication</a>:
  replSetName: rs0
</code></pre>

<pre class="language-mongodb"><code class="lang-mongodb">rs.initiate({ _id: "rs0", version: 1,
members: [
  { _id: 0, host : "<a data-footnote-ref href="#user-content-fn-2">[MONGO_HOST]</a>:[MONGO_PORT]" }, 
  ...
]})
</code></pre>

</details>

<details>

<summary>Kafka</summary>

* [ ] Deploy a Kafka instance or cluster, to be used as the main messaging system (while optional, it is recommended as it allows async services and centralized command management)

</details>

<details>

<summary>Keycloak</summary>

* [ ] Deploy a Keycloak instance or cluster, to be used as the authentication provider (unless solution will be used insecurely for development or a state authentication provider will be used instead)&#x20;

</details>

* [ ] If deployed as [VM instances](#user-content-fn-3)[^3], set tags / labels for deployed systems as follows, which will enable automated population of system addresses in Ansible playbooks:

| Instances | AWS (tags:Name) | GCP (labels) |
| --------- | --------------- | ------------ |
| MongoDB   | mongodb         | mongodb      |
| Kafka     | kafka           | kafka        |
| Keycloak  | keycloak        | keycloak     |

{% hint style="info" %}
**Why don't we bundle these systems to our solution?**

While it is possible to bundle these systems into our deployment packages and enable one-click deployments, it goes against our open architecture principles, where we let our clients replace any external system in our solution architecture or use their existing components for the same.

Also, these are the systems where private customer and commercially sensitive enterprise data is stored, hence we give our clients full control over their deployment and configuration (such as configuring authentication, encryption of data in transit and at rest). &#x20;

If you don't already have these systems or would like to automated their deployment, check out vendor specific details for [installation options](https://docs.rierino.com/installation/deployment-alternatives/cloud-specific-details#provision-enabling-systems).&#x20;
{% endhint %}

## Set-up Initial Deployment Host

Depending on the option(s) you choose for the next step, install required tools on the machine you will be running deployments from

{% tabs %}
{% tab title="Cluster Provisioning" %}

* [ ] Install Terraform if you will be using it to provision the Kubernetes cluster:

{% embed url="<https://developer.hashicorp.com/terraform/downloads>" %}
Terraform Installation
{% endembed %}
{% endtab %}

{% tab title="Fully Automated Option" %}

* [ ] Install Ansible, collections and their dependencies, if you will be following fully automated deployment option:

{% embed url="<https://github.com/ansible/ansible>" %}
Ansible Installation
{% endembed %}

```sh
pip install kubernetes boto3 botocore
ansible-galaxy collection install kubernetes.core
```

{% endtab %}

{% tab title="All Options" %}

* [ ] For all cases, install kubectl and Helm:

{% embed url="<https://kubernetes.io/docs/tasks/tools/>" %}
kubectl Installation
{% endembed %}

{% embed url="<https://helm.sh/docs/intro/install/>" %}
Helm Installation
{% endembed %}

* [ ] Install cloud provider specific authentication tools[^4], Ansible collections[^5] and prerequisites[^6] as needed.&#x20;
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
You can also use the Rierino public Docker image specific to your cloud provider instead of manually installing these dependencies:
{% endhint %}

{% embed url="<https://hub.docker.com/u/rierino>" %}
Rierino Docker Deployment Images&#x20;
{% endembed %}

* [ ] Set-up your cloud access credentials that will be used by these tools as environment variables based on your cloud provider and the installed tools (e.g. AWS\_ACCESS\_KEY\_ID, AWS\_SECRET\_KEY for AWS deployment, kubeconfig file for kubectl)

{% hint style="info" %}
It is also possible to deploy remotely using helm charts without setting up such initial deployment host, but this approach is recommended as it provides more control and visibility during first deployment.
{% endhint %}

## Provision a Kubernetes Cluster

You will need to provision a Kubernetes cluster to deploy Rierino services ([unless you are deploying standalone containers](#user-content-fn-7)[^7]), which you can do manually through your cloud vendor UI or using Rierino [Terraform configuration](https://docs.rierino.com/installation/artifacts/terraform-configurations) below for your cloud service provider.&#x20;

* [ ] Create a Kubernetes cluster for Rierino services with the following node pools. If you already have a cluster, you can just create these node pools on that specific cluster.

<table><thead><tr><th width="232">Node Pool</th><th>Usage</th></tr></thead><tbody><tr><td>admin-node-pool</td><td>Used by admin gateway and runner pods</td></tr><tr><td>ui-node-pool</td><td>Used by admin UI pods</td></tr><tr><td>ops-node-pool</td><td>Used by CDC and calculation runner pods</td></tr><tr><td>infra-node-pool</td><td>Used by deployer pods</td></tr></tbody></table>

<details>

<summary>Terraform Option</summary>

If you choose to automate provisioning with Terraform, you can clone our [GitHub repository](#user-content-fn-8)[^8] and run the following commands:

<pre class="language-shell" data-overflow="wrap"><code class="lang-shell">git clone --branch release-[RIERINO_VERSION] https://[GIT_USER]:[GIT_TOKEN]@github.com/rierino-open/deployment
cd deployment/environments/[CLOUD]
terraform init
terraform plan <a data-footnote-ref href="#user-content-fn-9">-var="[VARIABLES]"</a>
terraform apply -var="[VARIABLES]"
</code></pre>

Terraform apply command will output kubeconfig contents, which should be saved as it will be required as an input file in following steps.

</details>

## Configure Network Connectivity

* [ ] Configure firewall settings of your cloud provider to ensure accessibility between the Kubernetes cluster (as well as [node to node](#user-content-fn-10)[^10]) and MongoDB, Kafka, Keycloak instances on required ports (or by providing all to all access adding them to a shared security group).
* [ ] Issue SSL certificates for load balancers that will be exposed externally.&#x20;
* [ ] Issue the following static IPs and DNS mappings for load balancers that will be exposed externally. Alternatively, you can use DNS mappings with load balancer public addresses once they are deployed on following steps.

| Static IP           | DNS Name            | Usage                          |
| ------------------- | ------------------- | ------------------------------ |
| admin-gateway-lb-ip | admin-api.\[DOMAIN] | External access to API gateway |
| admin-ui-lb-ip      | admin-ui.\[DOMAIN]  | External access to UI          |

{% hint style="info" %}
Rierino platform does not expose any resources publicly, other than the load balancer services.&#x20;

If you wish to access additional system components (such as MongoDB, Keyloak UI, etc.), you can configure their firewall and network settings manually to allow public access.
{% endhint %}

[^1]: Replication requires key file configuration when security.authorization is enabled. It is possible to set security.authorization to disabled for development purposes instead as well.

[^2]: Needs to be accessible between mongodb instances

[^3]: For kubernetes deployments of these systems, you can update ansible inventory file to include service endpoints instead

[^4]: Such as AWS CLI, gcloud CLI.

[^5]: Such as amazon.aws, google.cloud.

[^6]: Such as kubernetes pip package.

[^7]: If you will not be using Kubernetes for deployment, please contact Rierino team for deployment support

[^8]: You will need to use GitHub credentials issued for our repositories

[^9]: Example kv pairs or .tfvars when -var-file is used:&#x20;

    region="us-east-1"

    vpc\_id="vpc-1234"

    zones=\["us-east-1a", "us-east-1b"]

    admin\_cidr="123.123.123.123/32"

[^10]: Especially for pod to LB connections such as admin UI to admin gateway