From 43cd892e7d5aa69e7904af2e9c0271b89a5b8090 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:04:31 +0000 Subject: [PATCH 01/13] Clarify AppPack uses AWS CloudFormation, in a limited set of regions The Launch Pack URL is long and hard to read. Make it clear that we are using a pre-defined template so the reader understands the following steps are simply confirming the preset values. --- src/tutorials/initial-setup.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 8ee073e..3c889bb 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -15,7 +15,10 @@ 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. +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 | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------| From 901b021e2f901a03c38d06f37245a0f67431eec0 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:11:46 +0000 Subject: [PATCH 02/13] Correct the names of the AWS Regions in the Launch Stack list --- src/tutorials/initial-setup.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 3c889bb..4d2ca6e 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -20,17 +20,17 @@ 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` | +| 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` | From 909794a3717deb962629c154430c8a5794abbb5a Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:14:06 +0000 Subject: [PATCH 03/13] Reword the introduction to the form In the introduction above we state that the tutorial will use AWS CloudFormation. Here we inform the reader that it is a four step process. --- src/tutorials/initial-setup.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 4d2ca6e..3fdf9e0 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -32,9 +32,7 @@ We will use a pre-defined JSON template, so we can start using AppPack. | [![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` | - - -This will drop you into the AWS Cloudformation Stack creation form. It is split into four steps: +The process of creating an AWS CloudFormation Stack is divided into four steps: 1. **Specify template** * Click `Next` From ee9e9a1dc32ffccdcf2e4f8c5a7dd2d9d80ac09c Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:18:52 +0000 Subject: [PATCH 04/13] Escape the list used for each step and make the title bold --- src/tutorials/initial-setup.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 3fdf9e0..70282f7 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -34,15 +34,15 @@ We will use a pre-defined JSON template, so we can start using AppPack. The process of creating an AWS CloudFormation Stack is divided into four steps: -1. **Specify template** +**1\. Specify template** * Click `Next` -2. **Specify stack details** +**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** +**3\. Configure stack options** * Click `Next` -4. **Review** +**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` From 64e2024c5457192d1e5f031938f16e946a754743 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:20:14 +0000 Subject: [PATCH 05/13] Change the titles of each step so they match the form --- src/tutorials/initial-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 70282f7..0461010 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -42,7 +42,7 @@ The process of creating an AWS CloudFormation Stack is divided into four steps: 2. Click `Next` **3\. Configure stack options** * Click `Next` -**4\. Review** +**4\. Review and create** 1. At the bottom of the page, check the box for _I acknowledge that AWS CloudFormation might create IAM resources._ 2. Click `Create stack` From 233d8c0266e9b307b8e9b751047fa245523dfbc3 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:24:52 +0000 Subject: [PATCH 06/13] Add a note saying we can skip Step 1 --- src/tutorials/initial-setup.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 0461010..ab4c07b 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -35,7 +35,12 @@ We will use a pre-defined JSON template, so we can start using AppPack. The process of creating an AWS CloudFormation Stack is divided into four steps: **1\. Specify template** - * Click `Next` + +The first step is selecting the template to use. Since that was defined in the link, +we can skip this step: + +* 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) From 93738e17cf90ad70081753137f75648d1ffa7b94 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:26:24 +0000 Subject: [PATCH 07/13] Reformat Step 2 --- src/tutorials/initial-setup.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index ab4c07b..8c111b1 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -42,9 +42,13 @@ we can skip this step: * 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` + +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 and create** From f7c41ebe0e53a9d75fbd00ef70280fd7ffb5b600 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:28:23 +0000 Subject: [PATCH 08/13] Move the acknowledgement checkbox from Step 4 to Step 3 --- src/tutorials/initial-setup.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 8c111b1..e9c04f9 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -50,9 +50,13 @@ we can skip this step: 2. Click `Next` **3\. Configure stack options** - * Click `Next` + +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** - 1. At the bottom of the page, check the box for _I acknowledge that AWS CloudFormation might create IAM resources._ + 2. Click `Create stack` [^1]: See [Choose an AWS Region](../how-to/set-up/choose-aws-region.md) for more info From 623f6a6312bcc1cc3bfdca2452e93bc526881ffb Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:29:07 +0000 Subject: [PATCH 09/13] The title of the button has changed for Step 4 --- src/tutorials/initial-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index e9c04f9..8f669ad 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -57,7 +57,7 @@ we can skip this step: **4\. Review and create** - 2. Click `Create stack` +* Click `Submit` [^1]: See [Choose an AWS Region](../how-to/set-up/choose-aws-region.md) for more info From 9eb638a50323b2a59667b2b6070c6f4d71befbcc Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:39:17 +0000 Subject: [PATCH 10/13] Clarify that you must verify your email address before logging in The apppack.io, at least when using FireFox, goes into an infinite redirect loop if you don't. --- src/tutorials/initial-setup.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 8f669ad..44c2748 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -73,7 +73,9 @@ apppack auth login -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: From e4c3353abb5df7c4654945d661c605dcf9ebb995 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:46:36 +0000 Subject: [PATCH 11/13] Clarify that you must register (purchase) a domain for the cluster --- src/tutorials/initial-setup.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 44c2748..67cc31d 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -91,7 +91,10 @@ 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. 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` 👀). From 4fc9abe5f336dc08fa0dbe8ffe46aa353fc523c4 Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Fri, 7 Nov 2025 11:50:34 +0000 Subject: [PATCH 12/13] Add a reminder that DNS changes take time to propagate --- src/tutorials/initial-setup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index 67cc31d..a78126f 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -102,7 +102,8 @@ The easiest option here is to [register a new domain in your AWS console](https: ⏳ 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 From 4688718886a0117ed9c6affbfb32ddcd04c861ae Mon Sep 17 00:00:00 2001 From: Stuart MacKay Date: Sat, 8 Nov 2025 07:51:02 +0000 Subject: [PATCH 13/13] Correct the URL for registering a new domain --- src/tutorials/initial-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tutorials/initial-setup.md b/src/tutorials/initial-setup.md index a78126f..8f4bb79 100644 --- a/src/tutorials/initial-setup.md +++ b/src/tutorials/initial-setup.md @@ -96,7 +96,7 @@ The apps you create will be then available at the subdomain `https://{appname}.m This subdomain is typically just used within AWS. You can assign a custom domain for production. -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.