Skip to content

Changes to the tutorial #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StuartMacKay wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Changes to the tutorial #13

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
43cd892
Clarify AppPack uses AWS CloudFormation, in a limited set of regions
Nov 7, 2025
901b021
Correct the names of the AWS Regions in the Launch Stack list
Nov 7, 2025
909794a
Reword the introduction to the form
Nov 7, 2025
ee9e9a1
Escape the list used for each step and make the title bold
Nov 7, 2025
64e2024
Change the titles of each step so they match the form
Nov 7, 2025
233d8c0
Add a note saying we can skip Step 1
Nov 7, 2025
93738e1
Reformat Step 2
Nov 7, 2025
f7c41eb
Move the acknowledgement checkbox from Step 4 to Step 3
Nov 7, 2025
623f6a6
The title of the button has changed for Step 4
Nov 7, 2025
9eb638a
Clarify that you must verify your email address before logging in
Nov 7, 2025
e4c3353
Clarify that you must register (purchase) a domain for the cluster
Nov 7, 2025
4fc9abe
Add a reminder that DNS changes take time to propagate
Nov 7, 2025
4688718
Correct the URL for registering a new domain
Nov 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 48 additions & 28 deletions src/tutorials/initial-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,35 +15,49 @@ You'll need a few things ready to go to complete this tutorial. Make sure you've

⏳ _Estimated Time: 3 minutes_

Get started by clicking the "Launch Stack" button for your preferred region[^1] below. This will open up the AWS console and install the initial account-level resources so we can start using AppPack.

| Stack | Region |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| [![Create AppPack Stack in us-east-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-east-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | US East (Ohio) `us-east-2` |
| [![Create AppPack Stack in us-west-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-west-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | US West (Oregon) `us-west-2` |
| [![Create AppPack Stack in us-east-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-east-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | US East (N. Virginia) `us-east-1` |
| [![Create AppPack Stack in ap-northeast-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-northeast-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Seoul) `ap-northeast-2` |
| [![Create AppPack Stack in ap-south-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-south-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Mumbai) `ap-south-1` |
AppPack is currently available in a number of AWS Regions. Let's get started by
clicking the "Launch Stack" button for your nearest region[^1] below. This will
open the AWS Console to begin creating a resource Stack using AWS CloudFormation.
We will use a pre-defined JSON template, so we can start using AppPack.

| Stack | Region |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| [![Create AppPack Stack in us-east-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-east-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | US East (Ohio) `us-east-2` |
| [![Create AppPack Stack in us-west-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-west-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | US West (Oregon) `us-west-2` |
| [![Create AppPack Stack in us-east-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-east-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | US East (N. Virginia) `us-east-1` |
| [![Create AppPack Stack in ap-northeast-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-northeast-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Seoul) `ap-northeast-2` |
| [![Create AppPack Stack in ap-south-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-south-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Mumbai) `ap-south-1` |
| [![Create AppPack Stack in ap-southeast-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-southeast-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Singapore) `ap-southeast-1` |
| [![Create AppPack Stack in ap-southeast-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-southeast-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Sydney) `ap-southeast-2` |
| [![Create AppPack Stack in eu-north-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://eu-north-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | EU (Stockholm) `eu-north-1` |
| [![Create AppPack Stack in eu-west-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://eu-west-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | EU (London) `eu-west-2` |
| [![Create AppPack Stack in ap-southeast-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://ap-southeast-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Asia Pacific (Sydney) `ap-southeast-2` |
| [![Create AppPack Stack in eu-north-1](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://eu-north-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Europe (Stockholm) `eu-north-1` |
| [![Create AppPack Stack in eu-west-2](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://eu-west-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=apppack-account&templateURL=https%3A%2F%2Fs3.amazonaws.com%2Fapppack-cloudformations%2Flatest%2Faccount.json){target=_blank} | Europe (London) `eu-west-2` |

The process of creating an AWS CloudFormation Stack is divided into four steps:

**1\. Specify template**

This will drop you into the AWS Cloudformation Stack creation form. It is split into four steps:
The first step is selecting the template to use. Since that was defined in the link,
we can skip this step:

1. **Specify template**
* Click `Next`
2. **Specify stack details**
1. In the `Administrators` field, enter your email address and the email addresses of anyone else you'd like to grant full admin access to your account.
![create administrators screenshot](./../assets/create-administrators.png)
2. Click `Next`
3. **Configure stack options**
* Click `Next`
4. **Review**
1. At the bottom of the page, check the box for _I acknowledge that AWS CloudFormation might create IAM resources._
2. Click `Create stack`
* Click `Next`

**2\. Specify stack details**

1. In the `Administrators` field, enter your email address and the email addresses
of anyone else you'd like to grant full admin access to your account.
![create administrators screenshot](./../assets/create-administrators.png)

2. Click `Next`

**3\. Configure stack options**

1. In the `Capabilities` section, at the bottom of the screen, check the box titled
_I acknowledge that AWS CloudFormation might create IAM resources._
2. Click `Next`

**4\. Review and create**

* Click `Submit`

[^1]: See [Choose an AWS Region](../how-to/set-up/choose-aws-region.md) for more info

Expand All @@ -59,7 +73,9 @@ apppack auth login

<script id="asciicast-BkCDHIskycHdYNt3e8rMjbUAt" src="https://asciinema.org/a/BkCDHIskycHdYNt3e8rMjbUAt.js" data-rows="8" async></script>

You'll be able to login or create a new account if you don't have one already. If you login with an email address and password, be sure to verify your email address before continuing.
You'll be able to login, or create a new account if you don't have one already. If you
create an account, you MUST verify your email address, using the link sent to your
email address, before logging in.

Verify you are setup as an administrator:

Expand All @@ -75,15 +91,19 @@ You should see your AWS account listed in the output.

⏳ _Estimated time: 15 minutes_

You'll need to assign a domain to your cluster. If you used `example.com` for your cluster, apps you create on the cluster will be available at `https://{appname}.example.com`. You can use a custom domain for production apps, so this domain is typically just used internally.
You'll need to register and assign a domain for the cluster, e.g. `my-apppack-cluster.com`.
The apps you create will be then available at the subdomain `https://{appname}.my-apppack-cluster.com`.
This subdomain is typically just used within AWS. You can assign a custom domain for
production.
Copy link
Member

@ipmb ipmb Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may already have a domain registered.


The easiest option here is to [register a new domain in your AWS console](https://console.aws.amazon.com/route53/home#DomainRegistration:). Depending on the TLD you choose, they can be had for as little as $3/year (looking at you `.click` 👀).
The easiest option here is to [register a new domain in your AWS console](https://console.aws.amazon.com/route53/domains/home#/DomainSearch). Depending on the TLD you choose, they can be had for as little as $3/year (looking at you `.click` 👀).

!!! warning
⏳ This isn't an instant process, so be prepared to wait at least a few minutes for your domain to move from [Pending](https://console.aws.amazon.com/route53/home#DomainRequests:) to [Registered](https://console.aws.amazon.com/route53/home#DomainListing:). Also make sure you've [entered your billing info](https://console.aws.amazon.com/billing/home#/paymentmethods) in the AWS console to avoid any extra delay.

!!! info
If you'd rather use a domain you already own, see the [Bring Your Own Cluster Domain](../how-to/domains/bring-your-own-cluster-domain.md) how-to.
If you'd rather use a domain you already own, see the [Bring Your Own Cluster Domain](../how-to/domains/bring-your-own-cluster-domain.md)
how-to. It will always take a few minute for any DNS changes to propagate.

## 👷‍♀️ Create your cluster

Expand Down