# Install Orchestrator
###### tags: `Magma` `LTE` `EPC`

[TOC]

---

## Install the following tools

### Step 1: Prerequisites

We assume MAGMA_ROOT is set as described in the deployment intro.

This walkthrough assumes you already have the following

* a registered domain name
* a blank AWS account
* an AWS credential with admin permissions

If your AWS account is not blank, this can cause errors while Terraforming. If you know what you're doing, this is fine - otherwise, consider signing up for a new account.

Finally, our install process assumes the chosen region contains at least 3 availability zones. This should be the case for all major regions.


___
### Step 2: Assemble Certificates

Before Terraforming specific resources, we'll assemble the relevant certificates.

First, create a local directory to hold the certificates you will use for your Orchestrator deployment. These certificates will be uploaded to AWS Secrets Manager and you can delete them locally afterwards.

mkdir -p ~/secrets/certs
cd ~/secrets/certs

You will need the following 3 certs

1. TLS certificate
* CN: yourdomain.com
* SANs
* yourdomain.com
* *.yourdomain.com
* *.nms.yourdomain.com
2. TLS certificate's private key
3. TLS certificate's root CA certificate (which signed controller.crt)
If you aren't worried about a browser warning, you can generate self-signed certs. Though please note that using trusted certs in production deployments is encouraged

${MAGMA_ROOT}/orc8r/cloud/deploy/scripts/self_sign_certs.sh yourdomain.com


Alternatively, if you already have these certs, rename and move them as follows

1. Rename your public TLS certificate to controller.crt
2. Rename your TLS certificate's private key to controller.key
3. Rename your TLS certificate's root CA certificate to rootCA.pem
4. Put these three files under the directory you created above
Next, with the domain certs placed in the correct directory, generate the application certs

${MAGMA_ROOT}/orc8r/cloud/deploy/scripts/create_application_certs.sh yourdomain.com

>NOTE: yourdomain.com above should match the relevant Terraform variables in subsequent sections. For example, if in main.tf the orc8r_domain_name is orc8r.yourdomain.com, then that same domain should be used when requesting or generating all the above certs.

Finally, create the admin_operator.pfx file, protected with a password of your choosing

$ openssl pkcs12 -export -inkey admin_operator.key.pem -in admin_operator.pem -out admin_operator.pfx
Enter Export Password:
Verifying - Enter Export Password:


admin_operator.pem and admin_operator.key.pem are the files that NMS will use to authenticate itself with the Orchestrator API. admin_operator.pfx is for you to add to your keychain if you'd like to use the Orchestrator REST API directly (on macOS, double-click the admin_operator.pfx file and add it to your keychain, inputting the same password chosen above).

The certs directory should now look like this

$ ls -1 ~/secrets/certs/


---

### Step 3: Install Orchestrator
With the relevant certificates assembled, we can move on to Terraforming the infrastructure and application.

**Initialize Terraform**
Create a new root Terraform module in a location of your choice by creating a new `main.tf` file.

Follow the example Terraform root module at `orc8r/cloud/deploy/terraform/orc8r-helm-aws/examples/basic` but make sure to override the following parameters

* `orc8r_db_password` must be at least 8 characters
* `orc8r_domain_name` your registered domain name
* `seed_certs_dir` local certs directory (e.g. "~/secrets/certs")
* `orc8r_tag` tag used when you published your Orchestrator containers
* `orc8r_deployment_type` type of orc8r deployment (fwa, federated_fwa, all)
* `orc8r_db_engine_version` on fresh Orc8r installs, target Postgres 12.6
Make sure that the source variables for the module definitions point to `github.com/magma/magma//orc8r/cloud/deploy/terraform/MODULE?ref=v1.8.` Adjust any other parameters as you see fit. Check the READMEs for the relevant Terraform modules to see additional variables that can be set. You can override values that are part of the Terraform files that are used in the GitHub repository.

Finally, initialize Terraform

terraform init

> By default, Terraform state file will be stored locally. However, you can store the state file remotely using an AWS S3 bucket.

---

### Reference
* https://magma.github.io/magma/docs/orc8r/deploy_install