Quick start for vendors (Docker)

This quick start guide explains how to natively deploy an app in a Docker container in AWS, from the vendor perspective. 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 your Docker container 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 to customer appliances.

Prerequisites

Send an email to [email protected] and request an API key. You must have an API key to complete the quick start.
Create an AWS account for Tensor9. We will refer to this as the Tensor9 AWS account.

Note: Your Tensor9 AWS account must be located in a United States region. Support for non-US regions will be available in the near future.

Request the following AWS resource quota increases:
- Increase VPCs per region from 5 to 20. Go to your VPCs per region page to accomplish this.
- Increase Internet gateways per region from 5 to 20. Go to your Internet gateways per region page to accomplish this.

Launch an AWS EC2 instance

Go to your AWS EC2 dashboard.
Select any United States region. (Note: Support for other regions is coming soon.)
Select the Launch instances button.
Provide a name for your new instance.
Under Application and OS images, choose your desired configuration.

Important: You must use a Linux or MacOS machine image. Windows is not supported. For the purposes of deploying Nginx, we recommend using an Amazon Linux x86 Amazon Machine Image (AMI) with a t2.small instance type, but the needs of other apps may vary.

Select a new or existing Key pair that is appropriate for your environment, if needed.
Review the Network settings and Configure storage sections. These can be left at their defaults in most environments, but you can customize them, if needed.
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. Select the Create new IAM profile link, then select 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 select Create Role.
5. Go back to your Launch an instance tab and select the new instance profile that you just created.
Select Launch instance.

Install the Tensor9 CLI

Connect to your new AWS EC2 instance.
Install Java 17 or later. On Amazon Linux, use yum:

sudo yum install java

Install the AWS CLI. If you are using Amazon Linux, this is already installed by default.
Install the Tensor9 CLI:

curl https://t9-artifacts-prod-1.s3.us-west-2.amazonaws.com/tensor9-latest > tensor9 && chmod +x tensor9 && sudo tensor9 install

Set your Tensor9 API key:

export T9_API_KEY=<YOUR_API_KEY>

Note: An API key is required. If you do not have an API key, send email to [email protected] to request one.

Set up a Tensor9 control plane and Docker container

Set up a Tensor9 control plane in your new AWS account (this takes several minutes to complete) :

tensor9 vendor setup -cloud aws -region <YOUR-REGION>

Create a new Tensor9 app. As an example, we use Nginx:

tensor9 app create -name nginx-example -displayName "Nginx example app"

Install Docker, if it is not already installed:

sudo yum install docker

Verify that Docker is running:

sudo docker version

Prepare a docker container with your app. In this example, we download Nginx:

sudo docker pull nginx

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, select a repository link, and then select 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.
Bind your container as your new origin stack:

tensor9 stack bind -appName nginx-example -stackType DockerContainer -nativeStackId <YOUR_CONTAINER_URI>

You can find your container URI by checking the chosen docker image in the ECR repository. The URI should look like this:

<YOUR_TENSOR9_AWS_ACCOUNT_ID>.dkr.ecr.<YOUR-REGION>.amazonaws.com/<IMG_NAME>:<IMG_TAG>

Create a Tensor9 test appliance and test your app

Create a test appliance:

tensor9 test appliance create -appName nginx-example -name aws-test

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:

Create a release to your test appliance:

tensor9 stack release -appName nginx-example -testAppliance aws-test -vendorVersion "<YOUR_VERSION>" -description "<YOUR_DESCRIPTION>" -notes "<YOUR_NOTES>"

Visit the AWS CloudFormation Console in your region and search for a stack prefixed with “test-twin”. This is the digital twin stack for your test appliance.
Select the digital twin stack, then select Events and Timeline View. This view shows the deployment timeline of your stack to your test appliance.
Wait several minutes for the deployment to complete.
Select the Resources tab. Search for ECSCluster to find the ECS cluster digital twin that represents your test appliance’s stack.
Select the Service link. Here you can explore deployments, see which containers are running, and view logs and metrics.

Note: It takes several minutes for the appliance to provision hardware, download the docker container, and start publishing logs and metrics to your digital twin. When startup logs for Nginx appear in the container twin, then Nginx is running:

The load balancer in your digital twin should also show as healthy:

Run tensor9 report to find the DNS name of your appliance. The output has a line labeled DnsNameForLbAppliance, which is the DNS name.
Visit http://<DNS_NAME> 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.

Create a separate AWS account to simulate your customer.
Log into the AWS console. Verify that you have admin permissions.
Create a customer signup link:

tensor9 app signup-link -appName nginx-example

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.
Enter an email address and a company name, such as [email protected] and ExampleCompany.
Select the link to start the install process and provision infrastructure. Wait approximately 10 minutes for the infrastructure to finish provisioning.

After this short waiting period, the customer test appliance is 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.

Visit the digital twin for a customer appliance by searching for “twin” in the AWS CloudFormation console. Two digital twin stacks are displayed: One for your test appliance and the other for your customer appliance.

Note: The customer digital twin stack might not appear immediately. It takes approximately 10 minutes for your digital twin stack to deploy for the first time after the appliance is provisioned.

Select the link to the customer app digital twin stack.
Select the Resources tab, search for “service”, then select the Service link to view the ECS cluster digital twin 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 digital twin. When you see startup logs appearing in your container twin, then you know the customer app is running.

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 .
Visit http://<DNS_NAME_FOR_LB>: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 using the same Docker image tag you used to deploy the container.

Important: Verify that your container supports the amd64 platform.

Retire the current release:

tensor9 stack release retire -appName nginx-example -customerName examplecompany -vendorVersion "<YOUR_PREVIOUS_VERSION>"

Create a new release:

tensor9 stack release -appName nginx-example -customerName examplecompany -vendorVersion "<YOUR_NEW_VERSION>" -description "<YOUR_DESCRIPTION>" -notes "<YOUR_NOTES>"

Important: You must use a different -vendorVersion than the currently deployed app.

View your customer’s appliance in the AWS CloudFormation console to find the ECS cluster digital twin. 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.
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 .
Visit http://<DNS_NAME_FOR_LB>:80 to test Nginx on the customer appliance and verify that your code changes were applied.