Skip to content
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.

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

Simplify built-in quickstarts to a simple hello world #849

Merged
Merged
Show file tree
Hide file tree
Changes from 38 commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
0163474
NodeJS conflicts fixed
heitorlessa Dec 19, 2018
d53c02d
improv: Remove duplicate repo README on code tree
heitorlessa Dec 11, 2018
927d438
fix: Add correct CLI permission needed
heitorlessa Dec 11, 2018
48fc9b6
improv: Simplifies README and steps
heitorlessa Dec 11, 2018
b65bb11
improv: Simplifies Python boilerplate example and update tests
heitorlessa Dec 11, 2018
c539824
improv: Simplifies Go boilerplate example and update tests
heitorlessa Dec 11, 2018
d562ff8
fix: isBase64Encoded key now correctly set to Boolean
heitorlessa Dec 11, 2018
97210ec
fix: Address Sanath/Jacob feedback on tests folder/package.json
heitorlessa Dec 12, 2018
2a3f7d5
fix: Add functional sam build and npm run test preffix while we discu…
heitorlessa Dec 12, 2018
022b827
improv: Add event.json and remove env vars from template
heitorlessa Dec 12, 2018
777fbef
improv: Updates readme to include invoke with event.json, logs and ap…
heitorlessa Dec 12, 2018
a9323d4
improv: Simplify Java sample and update tests
heitorlessa Dec 12, 2018
b8cfc19
improv: Add Cleanup section
heitorlessa Dec 12, 2018
840e662
improv: Simplify DotNet Core sample
heitorlessa Dec 12, 2018
72208d9
fix: Trim whitespace on external link
heitorlessa Dec 12, 2018
0c6abaa
improv: Simplify Ruby and all steps work now too
heitorlessa Dec 12, 2018
68e72c9
fix: Remove unused parameters in appendix for sam deploy
heitorlessa Dec 12, 2018
1caa66d
improv: Clean up parent README
heitorlessa Dec 12, 2018
667e265
feat: Address Jacob's feedback on help message upon project build
heitorlessa Dec 19, 2018
80c68f3
feat: Move Nodejs4.3/6.10 to a legacy template, add sam build under b…
heitorlessa Dec 21, 2018
e75f808
improv: sam package no longer needs --template-file for template.yaml…
heitorlessa Dec 21, 2018
012168e
fix: Correct headings under Appendix
heitorlessa Dec 21, 2018
1b5757f
improv: python simplification after rebase
heitorlessa Dec 21, 2018
7648247
improv: go and java simplification after rebase
heitorlessa Dec 21, 2018
5b91fc4
feat: Add next step message for both strongly styped vs dynamic
heitorlessa Dec 21, 2018
6c5a656
improv: dotnet simplification after rebase
heitorlessa Dec 21, 2018
a9ab5a4
fix: Correct documentation links now pointing to AWS Docs
heitorlessa Dec 21, 2018
89f2e40
improv: ruby simplification after rebase
heitorlessa Dec 21, 2018
8340bb5
fix: revert compiled lang templates
heitorlessa Jan 7, 2019
dd1d16f
improv: Removes NodeJS 4.3 template and option
heitorlessa Jan 7, 2019
14cb8f5
Revert "improv: Removes NodeJS 4.3 template and option"
heitorlessa Jan 7, 2019
58a4f3a
fix: Remove NodeJS 4.3 option from runtime selection
heitorlessa Jan 7, 2019
f02109e
fix: Defaults legacy to 6.10
heitorlessa Jan 7, 2019
a153a30
fix: Remove --template-file from package in Ruby instructions
heitorlessa Jan 10, 2019
f13ef65
fix: jacob's feedback on nodejs legacy folder rename to 6
heitorlessa Jan 11, 2019
348ef5b
fix: jacob's feedback on package.json and appendix commands
heitorlessa Jan 11, 2019
aeaf413
fix: jacob's feedback on README and links to SAM Spec on template too
heitorlessa Jan 11, 2019
d61e3e8
fix: revert dotnet original readmes
heitorlessa Jan 11, 2019
e685a94
Merge branch 'develop' into improv/simplify-init-quickstart-templates
jfuss Jan 14, 2019
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
29 changes: 25 additions & 4 deletions samcli/commands/init/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,34 @@ def do_cli(ctx, location, runtime, output_dir, name, no_input):
LOG.debug("Init command")
click.secho("[+] Initializing project structure...", fg="green")

no_build_msg = """
Project generated: {output_dir}/{name}

Steps you can take next within the project folder
===================================================
[*] Invoke Function: sam local invoke HelloWorldFunction --event event.json
[*] Start API Gateway locally: sam local start-api
""".format(output_dir=output_dir, name=name)

build_msg = """
Project generated: {output_dir}/{name}

Steps you can take next within the project folder
===================================================
[*] Install dependencies
[*] Invoke Function: sam local invoke HelloWorldFunction --event event.json
[*] Start API Gateway locally: sam local start-api
""".format(output_dir=output_dir, name=name)

no_build_step_required = (
"python", "python3.7", "python3.6", "python2.7", "nodejs", "nodejs4.3", "nodejs6.10", "nodejs8.10", "ruby2.5")
Copy link
Contributor

Choose a reason for hiding this comment

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

Lambda has moved nodejs4.3 to depreciated, meaning creating and updating functions is no longer allows/supported. Can we match that expectation here and remove creation of Nodejs.4.3 functions?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Awesome, done!

next_step_msg = no_build_msg if runtime in no_build_step_required else build_msg
Copy link
Contributor

Choose a reason for hiding this comment

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

What if a custom template takes in a the --runtime arg? This message may or may not be true then.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not sure what you mean by a custom template takes in 'a in the --runtime arg' -- This is a quick workaround until sam build fully supports all runtimes so the message will remain consistent and this will be deleted, though the workaround is flawed in the sense of as sam build supports more native runtimes this will need updating.

    no_build_step_required = (
        "python", "python3.7", "python3.6", "python2.7", "nodejs", "nodejs4.3", "nodejs6.10", "nodejs8.10", "ruby2.5")
    next_step_msg = no_build_msg if runtime in no_build_step_required else build_msg

--runtime arg is validated against the ones we support and no_build_step_required essentially borrows the ones that have sam build support.

What would you suggest instead?

Copy link
Contributor

Choose a reason for hiding this comment

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

I see. I was getting two PRs mixed up, where I thought we were passing runtime to cookiecutter examples that are passed to --location. You can ignore this comment and can handle in the other pr that enables that.


try:
generate_project(location, runtime, output_dir, name, no_input)
# Custom templates can implement their own visual cues so let's not repeat the message
if not location:
click.secho(
"[SUCCESS] - Read {name}/README.md for further instructions on how to proceed"
.format(name=name), bold=True)
click.secho(next_step_msg, bold=True)
click.secho("Read {name}/README.md for further instructions\n".format(name=name), bold=True)
click.secho("[*] Project initialization is now complete", fg="green")
except GenerateProjectFailedError as e:
raise UserException(str(e))
3 changes: 1 addition & 2 deletions samcli/local/init/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,8 @@
"python2.7": os.path.join(_templates, "cookiecutter-aws-sam-hello-python"),
"python": os.path.join(_templates, "cookiecutter-aws-sam-hello-python"),
"ruby2.5": os.path.join(_templates, "cookiecutter-aws-sam-hello-ruby"),
"nodejs6.10": os.path.join(_templates, "cookiecutter-aws-sam-hello-nodejs"),
"nodejs6.10": os.path.join(_templates, "cookiecutter-aws-sam-hello-nodejs6"),
"nodejs8.10": os.path.join(_templates, "cookiecutter-aws-sam-hello-nodejs"),
"nodejs4.3": os.path.join(_templates, "cookiecutter-aws-sam-hello-nodejs"),
"nodejs": os.path.join(_templates, "cookiecutter-aws-sam-hello-nodejs"),
"dotnetcore2.0": os.path.join(_templates, "cookiecutter-aws-sam-hello-dotnet"),
"dotnetcore2.1": os.path.join(_templates, "cookiecutter-aws-sam-hello-dotnet"),
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
MIT No Attribution
Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
Expand All @@ -11,4 +11,4 @@ INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,42 +1,20 @@
# Cookiecutter SAM for Node Lambda functions
# Cookiecutter NodeJS Hello-world for SAM based Serverless App

This is a [Cookiecutter](https://github.com/audreyr/cookiecutter) template to create a Serverless Hello World App based on Serverless Application Model (SAM) and NodeJS.

It is important to note that you should not try to `git clone` this project but use `cookiecutter` CLI instead as ``{{cookiecutter.project_name}}`` will be rendered based on your input and therefore all variables and files will be rendered properly.
A cookiecutter template to create a NodeJS Hello world boilerplate using [Serverless Application Model (SAM)](https://github.com/awslabs/serverless-application-model).

## Requirements

Install `cookiecutter` command line:

**Pip users**:

* `pip install cookiecutter`

**Homebrew users**:

* `brew install cookiecutter`

**Windows or Pipenv users**:

* `pipenv install cookiecutter`

**NOTE**: [`Pipenv`](https://github.com/pypa/pipenv) is the new and recommended Python packaging tool that works across multiple platforms and makes Windows a first-class citizen.
* [AWS SAM CLI](https://github.com/awslabs/aws-sam-cli)

## Usage

Generate a new SAM based Serverless App: `cookiecutter gh:aws-samples/cookiecutter-aws-sam-hello-nodejs`.

You'll be prompted a few questions to help this cookiecutter template to scaffold this project and after its completed you should see a new folder at your current path with the name of the project you gave as input.
Generate a boilerplate template in your current project directory using the following syntax:

**NOTE**: After you understand how cookiecutter works (cookiecutter.json, mainly), you can fork this repo and apply your own mechanisms to accelerate your development process and this can be followed for any programming language and OS.
* **NodeJS 8**: `sam init --runtime nodejs8.10`

> **NOTE**: ``--name`` allows you to specify a different project folder name (`sam-app` is the default)

# Credits

* This project has been generated with [Cookiecutter](https://github.com/audreyr/cookiecutter)


License
-------

This project is licensed under the terms of the [MIT License with no attribution](/LICENSE)

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -4,48 +4,33 @@ This is a sample template for {{ cookiecutter.project_name }} - Below is a brief

```bash
.
├── README.md <-- This instructions file
├── hello-world <-- Source code for a lambda function
│ ├── app.js <-- Lambda function code
│ ├── package.json <-- NodeJS dependencies
├── README.MD <-- This instructions file
├── event.json <-- API Gateway Proxy Integration event payload
├── hello_world <-- Source code for a lambda function
│ └── app.js <-- Lambda function code
│ └── package.json <-- NodeJS dependencies and scripts
│ └── tests <-- Unit tests
│ └── unit
│ └── test_handler.js
── template.yaml <-- SAM template
│ └── test-handler.js
── template.yaml <-- SAM template
```

## Requirements

* AWS CLI already configured with Administrator permission
{%- if cookiecutter.runtime == 'nodejs6.10' %}
* [NodeJS 6.10 installed](https://nodejs.org/en/download/releases/)
{%- elif cookiecutter.runtime =='nodejs4.3' %}
* [NodeJS 4.3 installed](https://nodejs.org/en/download/releases/)
{%- else %}
* [NodeJS 8.10+ installed](https://nodejs.org/en/download/)
{%- endif %}
* [Docker installed](https://www.docker.com/community-edition)

## Setup process

### Building the project
### Local development

[AWS Lambda requires a flat folder](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-create-deployment-pkg.html) with the application as well as its dependencies in a node_modules folder. When you make changes to your source code or dependency manifest,
run the following command to build your project local testing and deployment:

```bash
sam build
```
**Invoking function locally using a local sample payload**

If your dependencies contain native modules that need to be compiled specifically for the operating system running on AWS Lambda, use this command to build inside a Lambda-like Docker container instead:
```bash
sam build --use-container
sam local invoke HelloWorldFunction --event event.json
```

By default, this command writes built artifacts to `.aws-sam/build` folder.

### Local development

**Invoking function locally through local API Gateway**

```bash
Expand All @@ -72,7 +57,7 @@ AWS Lambda NodeJS runtime requires a flat folder with all dependencies including

```yaml
...
FirstFunction:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello-world/
Expand All @@ -89,7 +74,6 @@ Next, run the following command to package our Lambda function to S3:

```bash
sam package \
--template-file template.yaml \
--output-template-file packaged.yaml \
--s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME
```
Expand All @@ -103,16 +87,29 @@ sam deploy \
--capabilities CAPABILITY_IAM
```

> **See [Serverless Application Model (SAM) HOWTO Guide](https://github.com/awslabs/serverless-application-model/blob/master/HOWTO.md) for more details in how to get started.**
> **See [Serverless Application Model (SAM) HOWTO Guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-quick-start.html) for more details in how to get started.**

After deployment is complete you can run the following command to retrieve the API Gateway Endpoint URL:

```bash
aws cloudformation describe-stacks \
--stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }} \
--query 'Stacks[].Outputs'
--query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \
--output table
```

## Fetch, tail, and filter Lambda function logs

To simplify troubleshooting, SAM CLI has a command called sam logs. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug.

`NOTE`: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

```bash
sam logs -n HelloWorldFunction --stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }} --tail
```

You can find more information and examples about filtering Lambda function logs in the [SAM CLI Documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html).

## Testing

We use `mocha` for testing our code and it is already added in `package.json` under `scripts`, so that we can simply run the following command to run our tests:
Expand All @@ -123,38 +120,87 @@ npm install
npm run test
```

## Cleanup

In order to delete our Serverless Application recently deployed you can use the following AWS CLI Command:

```bash
aws cloudformation delete-stack --stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }}
```

## Bringing to the next level

Here are a few things you can try to get more acquainted with building serverless applications using SAM:

### Learn how SAM Build can help you with dependencies

* Uncomment lines on `app.js`
* Build the project with ``sam build --use-container``
* Invoke with ``sam local invoke HelloWorldFunction --event event.json``
* Update tests

### Create an additional API resource

* Create a catch all resource (e.g. /hello/{proxy+}) and return the name requested through this new path
* Update tests

### Step-through debugging

* **[Enable step-through debugging docs for supported runtimes]((https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-debugging.html))**

Next, you can use AWS Serverless Application Repository to deploy ready to use Apps that go beyond hello world samples and learn how authors developed their applications: [AWS Serverless Application Repository main page](https://aws.amazon.com/serverless/serverlessrepo/)

# Appendix

## AWS CLI commands
## Building the project

[AWS Lambda requires a flat folder](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-create-deployment-pkg.html) with the application as well as its dependencies in a node_modules folder. When you make changes to your source code or dependency manifest,
run the following command to build your project local testing and deployment:

```bash
sam build
```

If your dependencies contain native modules that need to be compiled specifically for the operating system running on AWS Lambda, use this command to build inside a Lambda-like Docker container instead:
```bash
sam build --use-container
```

By default, this command writes built artifacts to `.aws-sam/build` folder.

## SAM and AWS CLI commands

AWS CLI commands to package, deploy and describe outputs defined within the cloudformation stack:
All commands used throughout this document

```bash
# Invoke function locally with event.json as an input
sam local invoke HelloWorldFunction --event event.json

# Run API Gateway locally
sam local start-api

# Create S3 bucket
aws s3 mb s3://BUCKET_NAME

# Package Lambda function defined locally and upload to S3 as an artifact
sam package \
--template-file template.yaml \
--output-template-file packaged.yaml \
--s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME

# Deploy SAM template as a CloudFormation stack
sam deploy \
--template-file packaged.yaml \
--stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }} \
--capabilities CAPABILITY_IAM \
--parameter-overrides MyParameterSample=MySampleValue
--capabilities CAPABILITY_IAM

# Describe Output section of CloudFormation stack previously created
aws cloudformation describe-stacks \
--stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }} --query 'Stacks[].Outputs'
--stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }} \
--query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \
--output table

# Tail Lambda function Logs using Logical name defined in SAM Template
sam logs -n HelloWorldFunction --stack-name {{ cookiecutter.project_name.lower().replace(' ', '-') }} --tail
```

**NOTE**: Alternatively this could be part of package.json scripts section.

## Bringing to the next level

Here are a few ideas that you can use to get more acquainted as to how this overall process works:

* Create an additional API resource (e.g. /hello/{proxy+}) and return the name requested through this new path
* Update unit test to capture that
* Package & Deploy

Next, you can use the following resources to know more about beyond hello world samples and how others structure their Serverless applications:

* [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/)
Loading