> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quick start: CloudFormation
This quick start guide demonstrates how to use Tensor9 with an existing application stack that is already modeled in CloudFormation. Tensor9 provides a click-to-install UI experience for your customers, as well as an AWS console and Tensor9 CLI control plane experience for your team.
As you follow this guide, you will:
* Set up a Tensor9 control plane in your AWS account, create a Tensor9 app, and bind an AWS CloudFormation stack as the origin for that app. In this guide, we use Nginx as an example app.
* Test your app running natively in AWS before rolling it out to customers.
* Try the customer click-to-install experience.
* Explore your control plane in the AWS Console that allows you to observe and operate all customer appliances.
* Deploy code changes and monitor them rolling out to customer appliances.
## Prerequisites
* Send an email to [hello@tensor9.com](mailto:hello@tensor9.com) and request:
* An API key. You must have an API key to complete the quick start.
* A CloudFormation template to create your origin stack for the Nginx sample app.
* Create an AWS account for Tensor9. We will refer to this as the Tensor9 AWS account.
**Important:**
* Your Tensor9 AWS account should be a dedicated AWS account used only for Tensor9. This reduces the risk of conflicts between your app deployed in a Tensor9 appliance and any other software, infrastructure, or resources you might have in a general-purpose AWS account.
* Your Tensor9 AWS account must be located in a United States region. Support for non-US regions will be available in the near future.
## Launch an AWS EC2 instance
To use the Tensor9 CLI, you need to set up an AWS EC2 instance.
1. Go to your [AWS EC2 dashboard](http://console.aws.amazon.com/ec2/).
2. Select any **United States** region. (**Note:** Support for other regions is coming soon.)
3. Click the **Launch instances** button.
4. Provide a name for your new instance.
5. Under **Application and OS images**, choose your desired configuration.
**Important:** You must use an x86 Linux or MacOS machine image. Windows is not supported. For the purposes of deploying Nginx, we recommend using an Ubuntu x86 Amazon Machine Image (AMI) with a t2.small instance type and at least 20GB of storage, but the needs of other apps may vary.
6. Select a new or existing **Key pair** to log in via SSH, if needed. (You can alternatively access your instance via Session Manager.)
7. Review the **Network settings** section. These can be left at their defaults in most environments, but you can customize them, if needed.
8. In the **Configure storage** section, increase your storage to at least 20GB.
9. Under **Advanced details**, select an IAM instance profile that has the **AdministratorAccess** policy assigned to the role. If you do not have such a profile:
1. Click the **Create new IAM profile** link, then click the **Create role** button.
2. Select **EC2** as **Service or use case**.
3. Search for and select **AdministratorAccess** to add the policy to the role.
4. Name the role and click **Create Role**.
5. Return to your **Launch an instance** tab and select the new instance profile that you just created.
10. Click **Launch instance**.
## Install the Tensor9 CLI
1. Connect to your new AWS EC2 instance.
2. [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
3. Install the Tensor9 CLI and set your API key:
Install the **tensor9** CLI via Homebrew (recommended):
```bash theme={null}
brew tap tensor9ine/tensor9
brew install tensor9
```
Alternatively, install via the install script:
```bash theme={null}
curl -sSL https://t9-artifacts-prod-1.s3.us-west-2.amazonaws.com/install-latest.sh | sh
```
Then set your Tensor9 API key:
```bash theme={null}
export T9_API_KEY=
```
**Note:** An API key is required. If you do not have an API key, send email to [hello@tensor9.com](mailto:hello@tensor9.com) to request one.
## Set up a Tensor9 control plane and Docker container
1. Set up a Tensor9 control plane in your new AWS account (this takes several minutes to complete):
```bash theme={null}
tensor9 vendor setup \
-cloud aws \
-region
```
2. Create a new Tensor9 app. As an example, we use Nginx:
`tensor9 app create -name nginx-example -displayName "Nginx example app"`
**Note:** The length of the `displayName` field must be 32 characters or fewer.
3. Install Docker, if it is not already installed:
`sudo apt install docker.io`
4. Verify that Docker is running:
`sudo docker version`
5. Prepare a docker container with your app. In this example, we download Nginx:
`sudo docker pull nginx`
6. Push your container to a repository in the Elastic Container Registry (ECR) in your Tensor9 AWS account. For more information and for a list of push commands, go to [your list of private repositories](http://console.aws.amazon.com/ecr/private-registry/repositories), click a repository link, and then click the **View push commands** button.
**Note:** The list of push commands includes a `build` step, but because you are pulling down an existing Docker container for Nginx, you do not need to complete the `build` step. The `build` step is only required if you are building your own container. If you are building your own container, make sure the container supports the linux/amd64 architecture.
## Set up a CloudFormation origin stack
Now you will create a new CloudFormation stack from your Tensor9 template.
1. Go to the AWS CloudFormation Console in your region.
2. Click the **Create stack** button, then click **With new resources**.
3. Click **Choose an existing template**, then click **Upload a template file**. Upload the CloudFormation template that you previously obtained from Tensor9, then click **Next**. If you do not have a CloudFormation template, send email to [hello@tensor9.com](mailto:hello@tensor9.com).
4. Enter a stack name for your new stack (32 characters or fewer, such as `t9-quickstart-origin-stack`), then click **Next**.
5. On the **Configure Stack Options** screen, you can leave all settings at their defaults. Check the checkbox next to **I acknowledge that AWS CloudFormation might create IAM resources** and click **Next**.
6. Review all settings, then click the **Submit** button to create your stack. The stack takes several minutes to be created.
7. After your new stack is created, click on its name to find its Amazon Resource Name (ARN). The ARN of the stack shows as the **Stack ID**.
8. Bind your stack as the new origin stack:
```bash theme={null}
tensor9 stack bind \
-appName nginx-example \
-stackType CloudFormation \
-nativeStackId
```
## Create a Tensor9 test appliance and test your app
1. Create a test appliance:
```bash theme={null}
tensor9 test appliance create \
-appName nginx-example \
-name aws-test
```
2. View the output of `tensor9 report` to determine when your test appliance is ready for a release. While the test appliance is creating, `tensor9 report` displays output such as:
When the appliance is ready, `tensor9 report` displays output such as:
3. Create a release to your test appliance:
```bash theme={null}
tensor9 stack release create \
-appName nginx-example \
-testApplianceName aws-test \
-vendorVersion "" \
-description "" \
-notes ""
```
4. After a few minutes, go to the AWS CloudFormation Console in your region and search for your test appliance name. This is the deployment stack for your test appliance.
5. Select the deployment stack, then click **Events** and **Timeline View**. This view shows the deployment timeline of your stack to your test appliance.
6. Wait several minutes for the deployment to complete.
7. Click the **Resources** tab. Search for **ECSCluster** to find the ECS cluster resource in your test appliance's deployment stack.
8. Click the link in the **Service name** column. Here you can explore deployments, see which containers are running, and view logs and metrics.
**Note:** It takes at least 10–15 minutes for the appliance to provision hardware, download the docker container, and start publishing logs and metrics to your deployment stack. When startup logs for Nginx appear in the container, then Nginx is running:
The load balancer in your deployment stack should also show as healthy:
8. Run `tensor9 report` to find the DNS name of your appliance. The output has a line labeled **DnsNameForLbAppliance**, which is the DNS name.
9. Visit `http://` to verify that Nginx is working.
## Testing the customer install process
As a vendor providing services to customers, you can test your environment by going through the process of installing your app from the perspective of a customer.
1. Create a separate AWS account to simulate your customer.
2. Log into the AWS console as your simulated customer. Verify that you have admin permissions.
3. Create a customer signup link:
`tensor9 app signup-link -appName nginx-example`
4. Visit the signup link in the same browser window that you used to log into the AWS console as a simulated customer. A signup screen displays and prompts you for your company information and email address.
5. Enter an email address and a company name, such as [data@examplecompany.com](mailto:data@examplecompany.com) and ExampleCompany, then click the link that appears. The AWS **Quick create stack** screen opens in a new browser tab.
6. On the **Quick create stack** screen, check the checkbox next to **I acknowledge that AWS CloudFormation might create IAM resources** and click the **Create stack** button.
7. Return to the signup page browser tab to click the **Continue** button.
8. Wait approximately 10 minutes for the infrastructure to finish provisioning.
The customer test appliance is now ready for use.
Next, we will explore the control plane for this customer appliance.
## Explore your control plane in AWS
AWS is your control plane for all your customer appliances. You can view the status of your customer appliances in AWS.
1. Visit the deployment stack for a customer appliance by searching for your customer name in the AWS CloudFormation console. Two deployment stacks are displayed: One for your test appliance and the other for your customer appliance.
**Note:** The customer deployment stack might not appear immediately. It takes approximately 10 minutes for your deployment stack to deploy for the first time after the appliance is provisioned.
2. Click the link to the customer app deployment stack.
3. Click the **Resources** tab, search for "service", then click the **Service** link to view the ECS cluster for your customer.
**Note:** Logs and metrics might not appear immediately. It takes several minutes for your customer's appliance to provision hardware, download your docker container, and start publishing logs and metrics to your deployment stack. When you see startup logs appearing in your container, then you know the customer app is running.
4. Run `tensor9 report` and look for a line labeled **DnsNameForLbAppliance** in the **Customer Appliances** section of the output. This is the DNS name for the customer appliance. For example, `nginx--LbApp-tAUAT8tDV5hn-0c7199c912e8827d.elb.us-west-2.amazonaws.com` .
5. Visit `http://:80` to use Nginx as if you were the customer.
## Release a code change
At any time, you can make a code change, build the latest container, and push it to Elastic Container Registry in your Tensor9 AWS account. You must use a Docker image tag that is different from the tag you originally used to deploy the container.
**Important:** Verify that your container supports the linux/amd64 platform.
1. Prepare your updated Docker container, then tag the container and push it to your ECR repository just as you did in the [Set up a Tensor9 control plane and Docker container](#set-up-a-tensor9-control-plane-and-docker-container) section.
2. Modify the CloudFormation stack template that you used in the [Set up a CloudFormation origin stack](#set-up-a-cloudformation-origin-stack) section so that it has the URI of the new container you just pushed to your ECR repository.
3. Go to your AWS CloudFormation console and select your Tensor9 origin stack, then click **Update stack** > **Make a direct update**. On the next screen, click **Replace existing template**. Select the template you modified in the previous step, then click the **Next** button.
4. On the following screen, make any modifications that are appropriate for your environment, then click **Next**. On the **Configure stack options** screen, check the checkbox next to **I acknowledge that AWS CloudFormation might create IAM resources**, then click **Next**.
5. On the **Review** screen, verify that all the changes look correct. When you are ready, click the **Submit** button. The stack takes several minutes for update to complete.
6. Retire the current release:
```bash theme={null}
tensor9 stack release retire \
-appName nginx-example \
-customerName examplecompany \
-vendorVersion ""
```
7. Create a new release:
```bash theme={null}
tensor9 stack release create \
-appName nginx-example \
-customerName examplecompany \
-vendorVersion "" \
-description "" \
-notes ""
```
**Important:** You must use a different `-vendorVersion` than the currently deployed app.
8. Inspect your customer's deployment stack in the AWS CloudFormation console to find the ECS cluster. A recent blue or green deployment for your change appears. The old software will not be turned off until the new software is up and passing health checks.
9. Run `tensor9 report` and look for a line labeled **DnsNameForLbAppliance** in the **Customer Appliances** section. This is the DNS name for the customer appliance. For example, `nginx-LbApp-6SOn9F6auFHS-bb813efec3dd0c2c.elb.us-west-2.amazonaws.com` .
10. Visit `http://` to test Nginx on the customer appliance and verify that your code changes were applied.