This guide walks you through packaging an AWS ECS application and deploying it to an install.

All the configuration and component code used in this guide can be found in our Guides repo.

​
Prerequisites

​
What You Will Create

This tutorial will walk you through creating the following:

​
Configure App

To configure the app, you will create a TOML config file using our CLI. In each section below we will provide you with configuration snippets for the app itself as well as it’s components.

​
Create App

Define the app itself and give it a name. This will create the app in Nuon and generate a config file named nuon.demo_ecs_app.toml. This file will be populated with sample config, which we will update in this guide.

nuon apps create --name=demo_ecs_app

You should see the new app in the dashboard.

​
App Input

This is a setting that your customer will be able to configure when they install the app. It will be displayed on the installer page as a text field.

nuon.demo_ecs_app.toml
[inputs]
[[inputs.group]]
name = "app"
description = "App inputs"
display_name = "App inputs"

[[inputs.input]]
name = "service_name"
description = "What to name the ECS service"
default = "api"
sensitive = false
display_name = "Service Name"
group = "app"

​
Installer

Update the installer config. Installers provide an out-of-the-box installation flow your customers can use to install your app. You will use it later in this guide to create an install yourself.

nuon.demo_ecs_app.toml
[installer]
name               = "Demo ECS App"
description        = "A demo app that runs on ECS."
documentation_url  = "https://docs.nuon.co/"
community_url      = "https://join.slack.com/t/nuoncommunity/shared_invite/zt-1q323vw9z-C8ztRP~HfWjZx6AXi50VRA"
github_url         = "https://github.com/nuonco"
homepage_url       = "https://www.nuon.co/"
demo_url           = "https://www.nuon.co/"
logo_url           = "https://assets-global.website-files.com/62a2c1332b518a9eedc6de2f/651df2030c43865b9b16046b_Group%2048.png"
og_image_url       = "https://assets-global.website-files.com/62a2c1332b518a9eedc6de2f/651df2030c43865b9b16046b_Group%2048.png"
favicon_url        = "https://assets-global.website-files.com/62a2c1332b518a9eedc6de2f/651df2030c43865b9b16046b_Group%2048.png"
copyright_markdown = """
© 2024 Nuon.
"""
footer_markdown = """
[Terms of Service](https://nuon.co/terms)
"""
post_install_markdown = """
# Demo ECS App

Demo ECS App is being deployed.
"""
apps = ["demo_ecs_app"]

​
Sandbox

Update the sandbox config. The aws-ecs sandbox will provide everything you need to run ECS services, from the ECS Fargate cluster down to the VPC.

nuon.demo_ecs_app.toml
[sandbox]
terraform_version = "1.7.5"
[sandbox.public_repo]
directory = "aws-ecs"
repo = "nuonco/sandboxes"
branch = "main"

​
Runner

Update the runner config. The aws-ecs sandbox requires that we use the aws-ecs runner. The runner manages the sandbox, provisioning and deprovisioning AWS resources during deploys.

The aws-ecs runner is so named because it runs on ECS, but it can be used to manage any AWS resources. Since it runs on ECS Fargate, no resources beyond what is needed for the runner are provisioned by default. You can use our ECS sandbox and runner to manage Lambda or EC2 deployments without worrying about extraneous ECS costs.

nuon.demo_ecs_app.toml
[runner]
runner_type = "aws-ecs"

​
Sync App Config to Nuon

You now have a complete Nuon app config. This is a good place to stop and sync it to Nuon.

nuon apps sync --file=nuon.demo_ecs_app.toml

Select the app in the dashboard, and you should now see the updated inputs, sandbox, and runner configuration.

​
Connect Components

This app consists of two components: one to build the Docker image, and another to provision the ECS service.

​
Docker Image

This is a Docker Build component that will build the API and create a Docker image containing it. When released, it will sync the image to each install’s ECR so ECS can pull it when creating tasks.

nuon.demo_ecs_app.toml
[[components]]
name   = "docker_image"
type = "docker_build"
dockerfile = "Dockerfile"
[components.public_repo]
repo      = "nuonco/guides"
directory = "aws-ecs-tutorial/components/docker-image"
branch    = "main"

​
ECS Service

This component will create an ECS service using the docker image, and expose it to the internet with an ALB. It requires some info about the install it will run in, so we use Nuon variables to interpolate the required info on a per-install basis. See our Using Variables guide for more info about how this works.

nuon.demo_ecs_app.toml
[[components]]
name   = "ecs_service"
type = "terraform_module"
terraform_version = "1.7.5"
[components.public_repo]
repo      = "nuonco/guides"
directory = "aws-ecs-tutorial/components/ecs-service"
branch    = "main"
[components.vars]
service_name = "{{.nuon.install.inputs.service_name}}"
cluster_arn = "{{.nuon.install.sandbox.outputs.ecs_cluster.arn}}"
image_url = "{{.nuon.components.docker_image.image.repository.uri}}"
image_tag = "{{.nuon.components.docker_image.image.tag}}"
app_id = "{{.nuon.app.id}}"
org_id = "{{.nuon.org.id}}"
install_id = "{{.nuon.install.id}}"
vpc_id = "{{.nuon.install.sandbox.outputs.vpc.id}}"
domain_name = "api.{{.nuon.install.sandbox.outputs.public_domain.name}}"
zone_id = "{{.nuon.install.sandbox.outputs.public_domain.zone_id}}"

​
Sync Component Configs to Nuon

Now that you have the components, sync the update config to Nuon.

nuon apps sync --file=nuon.demo_ecs_app.toml

Select the “Components” tab in the dashboard to see the updated list of components.

​
Create an Install

Creating an install requires two steps: granting access to the AWS account via an IAM role, and then provisioning the install in that account. The easiest way to do this is to use the installer you configured earlier, via our installer UI template. You can find the template at https://github.com/nuonco/installer. Clone that and run it locally following the instructions in the README.

The installer UI will guide you through granting access to your AWS account, and provisioning the install. Expect this to take about 10 minutes.

For other ways to create and manage installs, see our guides Install Access Permissions and Create Installs.

​
Monitoring Installs

As soon as you kick off the install provisioning, you should see the new install in the dashboard.

Click on the install in the list to monitor the provisioning process and view other details about the install.

​
Inspect the Install

When the install has provisioned, and the deploys have completed, copy the install ID from the UI and curl the API to verify it’s running.

curl https://api.{install_id}.nuon.run/introspect/env

​
Wrapping Up and Next Steps

Congratulations, you just deployed a BYOC app to AWS! A few suggestions for where to go next:

  • Check out our Release Management guide to learn how to update installs.
  • Dig into our App Configuration guide to learn how to configure more complex apps.
  • Share your installer with a friend and have them install your app in their AWS account.