first-deployment-to-aws.md

First deployment to AWS

In this tutorial, you will make the first deployment of the LetsGo stack to your own AWS account. Upon completion, you will have the web and API components available on publicly accessible, secure URLs, and the worker and database components wired up and ready to use:

You will also have your local environment prepared for further development. This tutorial does not integrate Auth0 or Stripe - you will do this in separate tutorials.

NOTE This tutorial will deploy several artifacts to your AWS account. The cost of keeping them idle for a day is about $0.70 (that's 70 cents). It is easy to remove all of them when you are done.

Prerequisites

First, you need to install a few tools, configure your development environment, and create an AWS account if you don't have one already.

Node.js

LetsGo requires Node.js v18 or later. Follow the installation instructions for Node.js to complete this step. When you are done, you should be able to run the following:

$ node -v
v20.5.0

The reported version number should be >= 18.

yarn

LetsGo uses the yarn package manager v1.21 or later. It must be installed globally. Run the following to install the latest version of yarn:

npm i -g yarn

When done, you should be able to run the following:

$ yarn -v
1.21.1

The reported version number should be >= 1.21

git

You must have git installed and configured in the system. Follow the git installation instructions to complete this step. When you are done, you should be able to run the following:

$ git -v
git version 2.37.1 (Apple Git-137.1)

The version and platform may be different on your system.

Docker

You must have Docker installed on your system. Follow the Docker installation instructions to complete this step. When you are done, you should be able to run the following:

$ docker -v
Docker version 24.0.6, build ed223bc

The version and build may be different on your system.

AWS CLI

LetsGo requires that you have an Amazon Web Service (AWS) account and are able to access it using the AWS CLI installed locally.

1. To create a new AWS account, go here.
2. To install and configure AWS CLI, follow these instructions.

Note that the recommended authentication method for AWS CLI is to use short-lived tokens, and to manage users via AWS IAM Identity Center. You can enable AWS IAM Identity Center at no cost, and then set up users, groups, and appropriate permissions.

Once you have configured AWS IAM Identity Center to your liking, you can use the aws configure sso wizard to establish a session in your AWS CLI, as described here.

For security purposes, you can modify the session duration in AWS IAM Identity Center following these instructions.

When you are done, you should be able to run the following:

$ aws sts get-caller-identity
{
    "UserId": "AIDASVBBTE64I3S2RVCXN",
    "Account": "182606571448",
    "Arn": "arn:aws:iam::182606571448:user/tjanczuk"
}

The output of the command should describe your user's identity in AWS.

Clone the LetsGo repository

Go to a directory where you want to create a subdirectory with your project files and run:

git clone [email protected]:47chapters/letsgo.git

You now have a subdirectory called letsgo with a copy of the LetsGo project. Go to that subdirectory with:

cd letsgo

All subsequent commands in this tutorial must be run from the letsgo directory.

Install dependencies

Install all dependencies required by the project:

yarn install

Build the project

Build all components:

yarn build

Build the Docker images

Build the Docker images for the web, API, and worker components:

yarn buildx

Create your first LetsGo deployment in AWS

Run the LetsGo CLI command to create your first deployment in AWS:

yarn ops deploy -a all

This will run for several minutes and generate a lot of output with the last line reporting a successful deployment:

...
Deployed: all, api, db, web, worker

Get the URLs of the web and API components

Call this command to get the status of your deployment:

$ yarn ops status
Web
  Service
    Status         RUNNING
    Health         HTTP 200 (160ms)
    Url            https://gwdvbituqq.us-west-2.awsapprunner.com
...
Api
  Service
    Status         RUNNING
    Health         HTTP 200 (172ms)
    Url            https://6ucstfkcn6.us-west-2.awsapprunner.com
...

The output contains a report about the status of the web, API, worker, and database components of your deployment. In the Web and Api sections, locate the Url property. They are the public HTTPS URLs for the web and API components, respectively.

Validate deployment

Now, call the health endpoint of the API component with curl. The endpoint is the combination of the API's Url with the /v1/health path, e.g.:

$ curl https://gwdvbituqq.us-west-2.awsapprunner.com/v1/health
{"ok":true,"imageTag":"9225060f1903ddef","updatedAt":"2023-11-04T22:08:24.392Z"}

Notice the output is an HTTP 200 response with a JSON providing some basic information about the API component.

Lastly, navigate to the Web component's URL in the browser:

Congratulations! You have just made your first deployment of the LetsGo stack to your own AWS account. You are ready to start making changes and adjustments to the app, and the first step is to learn how to build and run the stack locally.