|
| 1 | +# SAM Deployment Guide |
| 2 | + |
| 3 | +If you plan to automate the deployment through your own infrastructure, deploy multiple instances to a single account, or if you just want to customize the template, you can do so using just the [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html). |
| 4 | + |
| 5 | +## Getting Started |
| 6 | + |
| 7 | +1. Install each of these if you haven't already: |
| 8 | + |
| 9 | + - [Git](https://git-scm.com/) |
| 10 | + - [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html) |
| 11 | + - [CloudFormation Linter (`cfn-lint`)](https://github.com/aws-cloudformation/cfn-python-lint) is recommended if you want to customize the template. |
| 12 | + |
| 13 | + If you have not used the AWS CLI or SAM CLI before, you may need to [configure your AWS credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html) as well. |
| 14 | + |
| 15 | + You can feel free to ignore the Docker requirement unless you wish to perform local test deployments using SAM. |
| 16 | + |
| 17 | +2. Create a private S3 bucket for putting zipped lambda functions and zipped templates in. Note the bucket name for the next step. (This can be the same one you used during in the initial deployment.) From here on out, we'll refer to this as `YOUR_LAMBDA_ARTIFACTS_BUCKET`, but you'll need to replace it accordingly. |
| 18 | + |
| 19 | +3. Pick a custom prefix for your application for your static assets and artifacts. This should be globally unique across all of AWS, like your org name, GitHub username, or similar. From here on out, we'll refer to this as `YOUR_CUSTOM_PREFIX`, but you'll need to replace it accordingly. |
| 20 | + |
| 21 | +4. Open a terminal (or Command Prompt window in Windows) and run the following two commands to clone this repo to your local drive and enter that directory. The command is the same for all platforms. |
| 22 | + |
| 23 | + ```bash |
| 24 | + git clone https://github.com/awslabs/aws-api-gateway-developer-portal.git |
| 25 | + cd aws-api-gateway-developer-portal |
| 26 | + ``` |
| 27 | + |
| 28 | +5. If desired, open the directory you cloned it to with your favorite text editor, modify the template (located at `cloudformation/template.yaml`) as desired and then run `cfn-lint` just to verify you didn't make any obvious mistakes. |
| 29 | +
|
| 30 | + > If you don't know where to find it, try looking at the prompt. If that doesn't contain any slashes, you can find it this way: |
| 31 | + > |
| 32 | + > - macOS, Linux, and similar: run `pwd` and it will print out the full current path. |
| 33 | + > - Windows: run `cd` and it should print out the current path. If that doesn't work, try `echo %cd%` instead. |
| 34 | + > |
| 35 | + > If you don't have a text editor like Notepad++ or Visual Studio Code installed, most operating systems have their own rudimentary text editor built-in, though it may be a little awkward to use. |
| 36 | + > |
| 37 | + > - Windows: `notepad.exe .\cloudformation\template.yaml` |
| 38 | + > - macOS: `open -a TextEdit ./cloudformation/template.yaml` |
| 39 | + > - Most Linux environments: `xdg-open ./cloudformation/template.yaml` |
| 40 | +
|
| 41 | +6. Open a terminal (or Command Prompt window in Windows) and run the following SAM CLI command to package the deployment. |
| 42 | +
|
| 43 | + ```bash |
| 44 | + # macOS, Linux, and similar |
| 45 | + sam package --template-file ./cloudformation/template.yaml \ |
| 46 | + --output-template-file ./cloudformation/packaged.yaml \ |
| 47 | + --s3-bucket "YOUR_LAMBDA_ARTIFACTS_BUCKET" |
| 48 | + ``` |
| 49 | +
|
| 50 | + ```bat |
| 51 | + rem Windows |
| 52 | + sam package --template-file .\cloudformation\template.yaml ^ |
| 53 | + --output-template-file .\cloudformation\packaged.yaml ^ |
| 54 | + --s3-bucket "YOUR_LAMBDA_ARTIFACTS_BUCKET" |
| 55 | + ``` |
| 56 | +
|
| 57 | + Do *not* run the `sam deploy` command suggested by the output of the above. While it works most of the time, it doesn't work if you need to customize anything, as we will need to. |
| 58 | + |
| 59 | +7. Run the following command in that same terminal to deploy. |
| 60 | + |
| 61 | + ```bash |
| 62 | + # macOS, Linux, and similar |
| 63 | + sam deploy --template-file ./cloudformation/packaged.yaml \ |
| 64 | + --stack-name "dev-portal" \ |
| 65 | + --s3-bucket "YOUR_LAMBDA_ARTIFACTS_BUCKET" \ |
| 66 | + --capabilities CAPABILITY_NAMED_IAM \ |
| 67 | + --parameter-overrides \ |
| 68 | + DevPortalSiteS3BucketName="YOUR_CUSTOM_PREFIX-dev-portal-static-assets" \ |
| 69 | + ArtifactsS3BucketName="YOUR_CUSTOM_PREFIX-dev-portal-artifacts" \ |
| 70 | + CognitoDomainNameOrPrefix="YOUR_CUSTOM_PREFIX" |
| 71 | + ``` |
| 72 | + |
| 73 | + ```bat |
| 74 | + rem Windows |
| 75 | + sam deploy --template-file .\cloudformation\packaged.yaml ^ |
| 76 | + --stack-name "dev-portal" ^ |
| 77 | + --s3-bucket "YOUR_LAMBDA_ARTIFACTS_BUCKET" ^ |
| 78 | + --capabilities CAPABILITY_NAMED_IAM ^ |
| 79 | + --parameter-overrides ^ |
| 80 | + DevPortalSiteS3BucketName="YOUR_CUSTOM_PREFIX-dev-portal-static-assets" ^ |
| 81 | + ArtifactsS3BucketName="YOUR_CUSTOM_PREFIX-dev-portal-artifacts" ^ |
| 82 | + CognitoDomainNameOrPrefix="YOUR_CUSTOM_PREFIX" |
| 83 | + ``` |
| 84 | + |
| 85 | + > Note: [`CAPABILITY_NAMED_IAM` is a value required by SAM, not a placeholder.](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html) |
| 86 | + |
| 87 | +8. If you have the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) installed, run the following command in that same terminal to get the newly deployed URL. You will need it for the remaining steps. |
| 88 | + |
| 89 | + ```bash |
| 90 | + # macOS, Linux, and similar |
| 91 | + aws cloudformation describe-stacks --query \ |
| 92 | + "Stacks[?StackName=='dev-portal'][Outputs[?OutputKey=='WebsiteURL']][][].OutputValue" |
| 93 | + ``` |
| 94 | + |
| 95 | + ```bat |
| 96 | + rem Windows |
| 97 | + aws cloudformation describe-stacks --query ^ |
| 98 | + "Stacks[?StackName=='dev-portal'][Outputs[?OutputKey=='WebsiteURL']][][].OutputValue" |
| 99 | + ``` |
| 100 | + |
| 101 | + Otherwise, you can do this by opening the CloudFormation console, opening your developer portal's stack, going to the "Outputs" tab, and searching for "WebsiteURL". This will show you the URL as a clickable link. |
| 102 | +
|
| 103 | +9. From here, [continue to the documentation on how to create an admin user for your newly created developer portal](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-developer-portal.html#apigateway-developer-portal-create-admin). |
| 104 | +
|
| 105 | +> If you have previously set up a v1 developer portal through the Serverless Application Repo, you will need to either remove all the v1 developer portal resources (dynamo tables, roles, etc.) or provide new names for the v2 developer portal by passing in parameter overrides for every resource. You will also want to choose a name other than `dev-portal` for the CloudFormation stack. |
| 106 | +
|
| 107 | +You can override any of the deployment settings using the `--parameter-overrides key="value"` format as demonstrated above. This will be necessary if you intend to deploy several instances of the developer portal or customize some of the features. You can see a full list of overridable parameters in `cloudformation/template.yaml` under the `Parameters` section as well as various documentation on it, and you can see an overview of the most common settings [in the developer portal documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-developer-portal.html#apigateway-developer-portal-settings). |
| 108 | +
|
| 109 | +## Updating |
| 110 | +
|
| 111 | +This assumes you already have this repo cloned. If you created it through SAR and wish to update through SAM, you can still do it this way, but you'll have to do the first two steps first to get the code. |
| 112 | + |
| 113 | +1. Open a terminal (or Command Prompt window in Windows) and run the following two commands to navigate to your local clone of the repo and update it. If you've made changes to the template, you may need to reconcile them accordingly—see the note in step 5 of [Getting Started](#getting-started) for info. |
| 114 | +
|
| 115 | + ```bash |
| 116 | + # macOS, Linux, and similar |
| 117 | + cd path/to/aws-api-gateway-developer-portal/ |
| 118 | + git pull |
| 119 | + ``` |
| 120 | +
|
| 121 | + ```bat |
| 122 | + rem Windows |
| 123 | + cd path\to\aws-api-gateway-developer-portal\ |
| 124 | + git pull |
| 125 | + ``` |
| 126 | +
|
| 127 | +2. Recall your choices for the CloudFormation stack name, assets bucket, and prefix as per steps 2 and 3 in the [Getting Started](#getting-started) instructions. (If you used entirely different names for the assets and artifacts buckets during creation, that's fine—just use those instead.) |
| 128 | + |
| 129 | +3. Update your deployment by performing steps 6 and 7 in the [Getting Started](#getting-started) instructions, but setting a `StaticAssetRebuildToken` value different from the previous one (it can be any arbitrary value). |
| 130 | + |
| 131 | + If you have the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) installed, you can run the following command in that same terminal to get the last used value. |
| 132 | + |
| 133 | + ```bash |
| 134 | + # macOS, Linux, and similar |
| 135 | + aws cloudformation describe-stacks --query \ |
| 136 | + "Stacks[?StackName=='dev-portal'][].Parameters[?ParameterKey=='StaticAssetRebuildToken'][].ParameterValue" |
| 137 | + ``` |
| 138 | + |
| 139 | + ```bat |
| 140 | + rem Windows |
| 141 | + aws cloudformation describe-stacks --query ^ |
| 142 | + "Stacks[?StackName=='dev-portal'][].Parameters[?ParameterKey=='StaticAssetRebuildToken'][].ParameterValue" |
| 143 | + ``` |
| 144 | + |
| 145 | + Otherwise, you can do this by opening the CloudFormation console, opening your developer portal's stack, going to the "Parameters" tab, and searching for "StaticAssetRebuildToken". |
0 commit comments