Skip to content

template.md

Latest commit

 

History

History
108 lines (66 loc) · 6.89 KB

template.md

File metadata and controls

108 lines (66 loc) · 6.89 KB

GitHub Actions workflows status

Deploy status Build status Docs generation status

CodeClimate

Repository initialization

When creating a repository from this template an init workflow (see here) will run. This workflow uses kaskadi-cli in order to properly initialize your repository by:

  • updating the names refering to the template in relevant files (for example package.json, package-lock.json, etc.) and renaming some files if need be
  • automatically adding your repository to Code Climate
  • automatically setting REPORTER_ID secret inside of your repository for test coverage upload to Code Climate. This may fail because of Code Climate infrastructure latency in setting up your repository. In such case your workflow will emit a warning telling you to set REPORTER_ID manually

Testing

mocha, chai, nyc, serverless-offline & standard are available as dev dependencies.

A build workflow (see here) is running on pull request and will execute your test suite before allowing you to merge your PR. It also has a coverage job already prepared that you can comment out as soon as your testing is in place and your REPORTER_ID is in the repository secrets. This is the ID on Code Climate used for uploading code coverage reports.

Beside running your unit tests, this workflow runs a static code analysis to find any vulnerability in your code. If a vulnerability is found, a notification will appear in the Security tab of your repository.

The build workflow also runs a syntax-check job which checks your serverless.yml file syntax.

Documentation

This repository comes with a generate-docs workflow that generates documentation automatically for you by reading your main serverless.yml configuration file and extracting meta data of all endpoints you defined. See here and there for more information.

Before generating the documentation, the workflow will check for syntax error in your serverless.yml file.

If you would like to see the workflow configuration, head here.

You can configure the template used to generate the action documentation here.

Deploying

Deploying to AWS is done automatically via a deploy workflow (see here). This workflow will run on push. Before publishing it:

  1. performs a static code analysis of the layer to detect any vulnerabilities. If a vulnerability is found, a notification will appear in the Security tab of your repository
  2. checks the syntax of serverless.yml for any errors
  3. run any tests you may have set up with npm test

You'll have to switch the command from --version to deploy -v in the workflow configuration file to actually deploy!

Warning: you may need to manually deploy the first time via Serverless CLI locally.

Tools

Add new endpoints

In order to add new endpoints:

  1. Go to the root of your API repository
  2. Run npm run add-lambda (this will prompt you for new lambda data)
  3. Your endpoint is now located under lambdas/<lambda_name> and you can start developing!

Upgrade API version

To update your API version, run npm run upgrade-version <version_option>. This takes the same argument as npm version (see here). It will update for you the main package.json as well as serverless.json but also all package.json for all endpoints.

Using custom domain for your API

For all custom domains you will need a certificate for this domain. Please make sure that you have the proper certificate generated, else create one associated with your domain. All this can be done here

Case 1: creating a new custom domain for API

If the custom domain you wish to use hasn't been created yet (list of custom domains here).

  1. Go here and click on Create Custom Domain Name
  2. Configure your domain as you wish to
  3. Once the domain is created and initialized, go to Route 53
  4. Go into the Hosted Zone for the domain you wish to use and create a new A Record.
  5. For this record, you should toggle the Alias option, give for name the custom domain name you wish to use and select for Alias target the API you want to map to this domain. You may need to copy paste the base URL to that API to make this work

Case 2: using an existing custom domain

  1. Go here
  2. Click on Edit for the custom domain you wish to use
  3. Add a base path you wish to map your API to for this domain and then select the API & its stage in the dropdown menus

Attention: you can only use an existing custom domain if this domain doesn't have already an empty path as base path.

{{>main}}