Update documentation to clarify support for multiple AWS accounts and multiple applications

[rocketnova]

Ticket

• Resolves Rename app or add multiple apps #569
• Resolves Create a guide for how to combine multiple platform templates into a single monorepo platform#20
• Resolves Support multi-app repos platform#15

Changes

What was added, updated, or removed in this PR.

• Update template-only-bin scripts for updating the template when there are multiple apps
• Add template-only-bin scripts for adding subsequent apps
• Revise existing documentation to clarify how to add multiple apps
• Add new documentation for multiple apps

Context for reviewers

Testing instructions, background context, more in-depth details of the implementation, and anything else you'd like to call out or ask reviewers.

This PR provides a comprehensive revision for all of the setup documentation, with an emphasis on providing clear and consistent guidance on how to set up a new project with one or more applications. It addresses existing setup and update instructions that are not clear and/or have circular dependencies (e.g. should you set up network first or app first?).

The new documentation uses the same format for all set up documents:

• Introduction
• Prerequisites
• Instructions
• Numbered headings for each instruction step

All of the documentation has been revised for basic technical writing best practices (e.g. active voice over passive voice, short clear sentences, define new terms, etc).

Note: this PR does not attempt to address #581.

Testing

Provide evidence that the code works as expected. Explain what was done for testing and the results of the test plan. Include screenshots, GIF demos, shell commands or output to help show the changes working as expected. ProTip: you can drag and drop or paste images into this textbox.

Testing setup

Our current scripting process recommends that users curl from the main branch of this repo, so the changes in this PR follow that same pattern. That means that testing requires a manual (noted below).

1. Checkout this branch (i.e. rocket/multi-app).
2. In /template-only-bin/download-and-install-app.sh, replace main/template-only-bin with rocket/multi-app/template-only-bin.
3. In /template-only-bin/update-template.sh, replace main/template-only-bin with rocket/multi-app/template-only-bin.

Test 1: Install into a project with a single app

1. Clone the nextjs template into a new directory.

   git clone [email protected]:navapbc/template-application-nextjs.git test-one-app 

2. Change into the new project directory

   cd test-one-app 

3. Dog-food the revised documentation in this PR. Start with the main README.md.

   1. Run the normal install script to install the latest main of the infra template.
   2. Run git commit after installing and before configuring the infra template, so you can easily verify changes using git diff.

4. Verify that the the full infra set up works as expected.

Screenshot showing a fully configured project

(No gif I created fit under the github file size limit of 10MB)

Test 2: Update a project with a single app

1. Using the test-one-app project dir from Test 1, follow the update directions.

   1. Normally, you would run the curl command, but because that runs the version of the script on main without the changes in this PR and you want to test the changes in this PR, instead run the following to update to the latest release version of the template:

   cat <PATH_TO_INFRA_TEMPLATE>/template-only-bin/update-template.sh | bash -s -- app v0.8.0 tag

2. Read the output and run git diff to verify changes.

Example output for updating to a branch

Example output for updating to a tag

Test 3: Install into a project with multiple apps

1. Clone the nextjs template into a new directory.

   git clone [email protected]:navapbc/template-application-nextjs.git test-multiple-apps 

2. Change into the new project directory

   cd test-multiple-apps 

3. Install the infra template. Run the normal install script to install the latest main of the infra template:

   curl https://raw.githubusercontent.com/navapbc/template-infra/main/template-only-bin/download-and-install-template.sh | bash -s

4. Run git commit to commit the installed infra template.

5. Before continuing with the remaining infra template installation steps, install a second app to the project by following these instructions.

   1. Name the application folder second-app.
   2. Normally, you would run the curl command, but because that runs the version of the script on main without the changes in this PR and you want to test the changes in this PR, instead run the following to update to the latest release version of the template:

   cat <PATH_TO_INFRA_TEMPLATE>/template-only-bin/download-and-install-app.sh | bash -s -- second-app

6. Run git commit to commit the installed second app.

7. Dog-food the revised documentation in this PR. Start with the main README.md. Make sure to follow the "For exach application" sections!

8. Verify that the the full infra set up works as expected

Screenshot showing a configured account + network

Screenshot showing the first configured app

Screenshot showing the second configured app

Test 4: Update a project with multiple apps

1. Using the test-multiple-app project dir from Test 3, follow the update directions.

   1. Normally, you would run the curl command, but because that runs the version of the script on main without the changes in this PR and you want to test the changes in this PR, instead run the following to update to the latest release version of the template:

     cat <PATH_TO_INFRA_TEMPLATE>/template-only-bin/update-template.sh | bash -s -- app,second-app rocket/multi-app branch
     ```
   

2. Read the output and run git diff to verify changes.

Example output for updating to a branch

[rocketnova]

@lorenyu This PR is really close to being fully done, but I would appreciate if you could give a WIP review of this draft so we can get aligned on the high level changes.

This should be a documentation-only PR. The current draft includes changes to template-only-bin and .github that I will pull into a separate PR and then I will adjust the documentation in this PR accordingly. That means that the testing instructions in this PR description do not apply.

[rocketnova]

Also, this PR does not yet incorporate recent PRs that have been merged, so I would also need to merge those changes in and update this documentation.

[rocketnova]

@lorenyu Also, if it's not clear, the entrypoint to review should be:

1. Start with: https://github.com/navapbc/template-infra/blob/rocket/multi-app/README.md
2. Click through the links starting with the "Setup" steps

[lorenyu]

I was actually thinking that we change install-template.sh so that it doesn't add any apps by default. Or we could call install-app at the end of install-template.

[lorenyu]

was thinking maybe we can make install-app.sh interactive where we can ask some initial configuration questions then configure the app for them. could also be a future enhancement

[lorenyu]

is this necessary? we already use sed in the template in a lot of places and i don't recall needing this.

[lorenyu]

i agree the convention should be dasherized, but i don't know how i feel about silently coercing it since if we normalize here we'll have to normalize in a lot of other places, and i don't think it should be the template's responsibility to do that. if we want to prevent underscores i'd rather just error out here. or even simpler i am ok with just leaving it as a convention but not actually preventing someone from using underscores.