This document will provide instructions on how to set up your local environment to utilize the Serverless Framework. It will also set up a connection to your AWS account, not the official SmokeDetector account.
Important Note: This document will set up a connection to your AWS account. That means that you may be charged for usage.
Serverless install requires the use of NodeJS. It requires Node v4 or higher. On Ubuntu 16.04, that should already be available by ensuring the system is up to date and performing:
sudo apt-get install nodejs
If you wish to use the current version - v9 as of this writing - you need to perform the following:
curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
sudo apt-get install -y nodejs
Validate your install by running:
nodejs -v
For this setup we are using 9.0.0
Run the following command to install the Serverless Framework. This will take a minute or two to complete.
npm install -g serverless
A very important note from the documentation:
To let the Serverless Framework access your AWS account, we're going to create an IAM User with Admin access, which can configure the services in your AWS account. This IAM User will have its own set of AWS Access Keys.
Note: In a production environment, we recommend reducing the permissions to the IAM User which the Framework uses. Unfortunately, the Framework's functionality is growing so fast, we can't yet offer you a finite set of permissions it needs (we're working on this). Consider using a separate AWS account in the interim, if you cannot get permission to your organization's primary AWS accounts.
We are going to set up admin credentials. Hopefully, at some point, the Serverless Framework community will provide the finite list of permissions needed. Until then, this is our method.
- Log into the AWS Console and go to the Identity and Access Management page
- Click Users
- Click Add User
- Enter a name that will identify the user properly (example:
smokey-serverless-admin) - Enable Programmatic access
- Click Next
- Click Attach existing policies directly
- Find AdministratorAccess and click Next
- Click Create user
- Copy the API Key and Secret to a temporary location. This will be needed in the next steps
Use serverless config credentials to store the AWS information.
serverless config credentials --provider aws --key XXXXXEXAMPLEXXXXAMPLE --secret example12345example67890example123456789
These credentials are stored in ~/.aws/credentials so that you can change them at a later time.
More advanced setups are described in the documentation, including different profiles for different environments.
In serverless.yml there is a region attribute. Set this to the Amazon Region value you want to deploy
the service in. Once that is done, if you wish to use boto3 to connect to the DynamoDB locally (not via
your deployed service), you also need to add the following to ~/.aws/config
[default]
region=us-east-1
Replace region value with the value you put in serverless.yml
If you are running stuff locally, you need to install boto3:
pip install boto3
We will be writing our service to use Python 3. We'll use the existing Serverless
template to do the initial set up and then modify serverless.yml as needed.
This command is going to create a subdirectory that will contain your service. Ensure you are at the correct location where you want this data saved, before executing the next command:
serverless create --template aws-python3 --path smoke_detector_aws
This will create a smoke_detector_aws directory. Change to that directory:
cd smoke_detector_aws
In the new directory are three files:
.gitignoreserverless.ymlhandler.py
- When defining a DynamoDB table, only define the columns that are part of the key.
An array of attributes that describe the key schema for the table and indexes.