Advanced Tutorial¶

In this second tutorial you will learn how to deploy a Python API project with Slam through a hands-on tutorial. In this tutorial you will use most features of Slam, and will have a small Python API deployed to AWS Lambda and API Gateway.

The screencast below is a recorded run through the entire tutorial. Feel free to use it as a reference when you go through the steps yourself, but note that it was created for an older release of Slam, so there are minor variations in the commands used.

Installing the Tutorial Project¶

To do this tutorial, you need to download a small API project that consists of two files:

Download these two files by right-clicking on the links above and selecting “Save link as...” to write them to your disk. Please put the files in a brand new directory.

The project uses a DynamoDB database, which is a AWS managed database service. To be able to run this project locally, you will need to download and run dynamodb-local.

Assuming you have dynamodb-local running, you set up and run this API with these commands:

$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt
(venv) $ python tasks_api.py

If you are following this tutorial on Windows, the virtual environment activation command (2nd line above) is venv\Scripts\activate.bat.

Once the API server is running, you can send requests to it at the address http://localhost:5000.

Configuration¶

This is going to be similar to what you did in the first tutorial. To begin, install the Slam utility with pip:

(venv) $ pip install slam

Now use the slam init command to create a starter configuration file:

(venv) $ slam init tasks_api:app --wsgi --stages dev,prod --dynamodb-tables tasks
The configuration file for your project has been generated. Remember to add slam.yaml to source control.

The above command generates a slam.yaml configuration file, with some initial settings. When you are working on a real project, you would want to add this file to source control, along with your own files. As your project evolves, you will hand edit this configuration file to make changes to your deployment.

Let’s go over the options included in the slam init command above one by one:

tasks_api:app is a standard notation used by Python web servers to designate the WSGI entry point of the application. What appears to the left of the colon, is the package or module where the WSGI callable instance is located. The name that appears to the right of the colon is the variable that holds the WSGI application instance. Slam uses this information to know where it needs to forward HTTP requests as they come into the Lambda function.
--wsgi indicates that this project should be deployed as a WSGI complaint web application.
--stages dev,prod creates two stages, named dev and prod. In slam, stages are independent versions of your deployed project. Having multiple stages allows you to deploy new features on one stage for development and testing purposes, while having a stable version of your project on another. You can create as many stages as you want. The first defined stage is configured as the default stage to receive new deployments. You will see later that Slam provides the tooling necessary to control what’s deployed to the additional stages.
--dynamodb-tables tasks creates a DynamoDB table called tasks for each defined stage. To make table names unique, Slam prefixes the requested name with the stage name. In this case, two DynamoDB tables will be created as part of this deployment, with names dev.tasks and prod.tasks.

Note that up to this point your AWS account has not been touched. All that has happened so far is configuration.

AWS Credentials¶

If you haven’t configured your AWS credentials yet, please go over the instructions to do so in the first tutorial.

Deployment¶

With the AWS credentials installed, you can now proceed to deploy this API project to AWS with the slam deploy command:

(venv) $ slam deploy
Building lambda package...
Deploying tasks-api...
tasks-api is deployed!
  Function name: tasks-api-Function-1D55AHXPNB02D
  S3 bucket: tasks-api-MHPGRXBK
  Stages:
    dev:$LATEST: https://ukhhy78b6a.execute-api.us-west-2.amazonaws.com/dev
    prod:$LATEST: https://ukhhy78b6a.execute-api.us-west-2.amazonaws.com/prod

The deployment process can take between one and two minutes. After the command finishes, you will have the API deployed!

The command shows the URLs where the two stages are exposed. Since this is the first deployment, both dev and prod are unversioned stages that are reported as $LATEST, which means that the track the most current version of the code. We will see how to create versions in the next secion of this tutorial.

At this point, you can send requests to the dev request URL and it should behave exactly like the version you tested locally on your computer.

Publishing a Version¶

Slam promotes a development cycle in which new versions of your project are deployed to your development stage, tested there, and then published to another stage, which could be a production stage, or maybe a staging stage.

When the project is published to a stage, it receives a permanent version number, which ensures the version running on that stage does not change regardless of what other code is deployed or published on other stages.

To publish the version of the API deployed in the previous section to the prod stage, the slam publish command is used:

(venv) $ slam publish prod
Publishing tasks-api:dev to prod...
tasks-api is deployed!
  Function name: tasks-api-Function-1D55AHXPNB02D
  S3 bucket: tasks-api-MHPGRXBK
  Stages:
    dev:$LATEST: https://ukhhy78b6a.execute-api.us-west-2.amazonaws.com/dev
    prod:1: https://ukhhy78b6a.execute-api.us-west-2.amazonaws.com/prod

Note that after the publish command completes, the prod stage is shown as prod:1, indicating that this stage is running version 1.

You can now continue working on the project, and run slam deploy to deploy the changes to the dev stage, and that is not going to affect the version of the project running on prod. If you want to upgrade the prod stage to a newer version of the project, just issue issue another slam publish prod command, and the current code in the dev stage will be used to upgrade prod, with a new version number.

Project Status¶

The status report that is shown after the deploy or publish commands run can also be requested on its own using the slam status command:

(venv) $ slam status
tasks-api is deployed!
  Function name: tasks-api-Function-1D55AHXPNB02D
  S3 bucket: tasks-api-MHPGRXBK
  Stages:
    dev: https://ukhhy78b6a.execute-api.us-west-2.amazonaws.com/dev
    prod:1: https://ukhhy78b6a.execute-api.us-west-2.amazonaws.com/prod

Deleting the Project¶

When you are done experimenting with this example project, you may want to remove it from your AWS account. If you want to perform a manual delete, you can just delete the Cloudformation stack and the S3 bucket used by this project, and that will leave your account clean of this deployment.

Alternatively, you can use the slam delete command, which performs the above two tasks for you:

(venv) $ slam delete
Deleting tasks-api...
Deleting logs...
Deleting files...

The End¶

Congratulations! You have reached the end of the second and last tutorial.

Please review the reference sections in this documentation for complete information on all the commands and the options available through the configuration file.