Zappa

Zappa - Serverless Python

About
Installation and Configuration
- Running the Initial Setup / Settings
Basic Usage
Executing in Response to AWS Events
Asynchronous Task Execution
Advanced Settings
- YAML Settings
Advanced Usage
Zappa Guides
Zappa in the Press
Sites Using Zappa
Related Projects
Hacks
Contributing
- Using a Local Repo

About

<a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/Miserlou/Talks/master/serverless-sf/big.quickstart.html"><img src="http://i.imgur.com/c23kDNT.png?1" alt="Zappa Slides"/></a> In a hurry? Click to see <a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/Miserlou/Talks/master/serverless-sf/big.quickstart.html">(now slightly out-dated) slides from Serverless SF</a>!

Zappa makes it super easy to build and deploy server-less, event-driven Python applications (including, but not limited to, WSGI web apps) on AWS Lambda + API Gateway. Think of it as "serverless" web hosting for your Python apps. That means infinite scaling, zero downtime, zero maintenance - and at a fraction of the cost of your current deployments!

If you've got a Python web app (including Django and Flask apps), it's as easy as:

$ pip install zappa
$ zappa init
$ zappa deploy

and now you're server-less! Wow!

What do you mean "serverless"?

Okay, so there still is a server - but it only has a 40 millisecond life cycle! Serverless in this case means "without any permanent infrastructure."

With a traditional HTTP server, the server is online 24/7, processing requests one by one as they come in. If the queue of incoming requests grows too large, some requests will time out. With Zappa, each request is given its own virtual HTTP "server" by Amazon API Gateway. AWS handles the horizontal scaling automatically, so no requests ever time out. Each request then calls your application from a memory cache in AWS Lambda and returns the response via Python's WSGI interface. After your app returns, the "server" dies.

Better still, with Zappa you only pay for the milliseconds of server time that you use, so it's many orders of magnitude cheaper than VPS/PaaS hosts like Linode or Heroku - and in most cases, it's completely free. Plus, there's no need to worry about load balancing or keeping servers online ever again.

It's great for deploying serverless microservices with frameworks like Flask and Bottle, and for hosting larger web apps and CMSes with Django. Or, you can use any WSGI-compatible app you like! You probably don't need to change your existing applications to use it, and you're not locked into using it.

Zappa also lets you build hybrid event-driven applications that can scale to trillions of events a year with no additional effort on your part! You also get free SSL certificates, global app deployment, API access management, automatic security policy generation, precompiled C-extensions, auto keep-warms, oversized Lambda packages, and many other exclusive features!

And finally, Zappa is super easy to use. You can deploy your application with a single command out of the box!

Awesome!

Installation and Configuration

Before you begin, make sure you are running Python 3.8/3.9/3.10/3.11/3.12 and you have a valid AWS account and your AWS credentials file is properly installed.

Zappa can easily be installed through pip, like so:

$ pip install zappa

Please note that Zappa must be installed into your project's virtual environment. The virtual environment name should not be the same as the Zappa project name, as this may cause errors.

(If you use pyenv and love to manage virtualenvs with pyenv-virtualenv, you just have to call pyenv local [your_venv_name] and it's ready. Conda users should comment here.)

Next, you'll need to define your local and server-side settings.

Running the Initial Setup / Settings

Zappa can automatically set up your deployment settings for you with the init command:

$ zappa init

This will automatically detect your application type (Flask/Django - Pyramid users see here) and help you define your deployment configuration settings. Once you finish initialization, you'll have a file named zappa_settings.json in your project directory defining your basic deployment settings. It will probably look something like this for most WSGI apps:

{
    // The name of your stage
    "dev": {
        // The name of your S3 bucket
        "s3_bucket": "lambda",

        // The modular python path to your WSGI application function.
        // In Flask and Bottle, this is your 'app' object.
        // Flask (your_module.py):
        // app = Flask()
        // Bottle (your_module.py):
        // app = bottle.default_app()
        "app_function": "your_module.app"
    }
}

or for Django:

{
    "dev": { // The name of your stage
       "s3_bucket": "lambda", // The name of your S3 bucket
       "django_settings": "your_project.settings" // The python path to your Django settings.
    }
}

Psst: If you're deploying a Django application with Zappa for the first time, you might want to read Edgar Roman's Django Zappa Guide.

You can define as many stages as your like - we recommend having dev, staging, and production.

Now, you're ready to deploy!

Basic Usage

Initial Deployments

Once your settings are configured, you can package and deploy your application to a stage called "production" with a single command:

$ zappa deploy production
Deploying..
Your application is now live at: https://7k6anj0k99.execute-api.us-east-1.amazonaws.com/production

And now your app is live! How cool is that?!

To explain what's going on, when you call deploy, Zappa will automatically package up your application and local virtual environment into a Lambda-compatible archive, replace any dependencies with versions with wheels compatible with lambda, set up the function handler and necessary WSGI Middleware, upload the archive to S3, create and manage the necessary Amazon IAM policies and roles, register it as a new Lambda function, create a new API Gateway resource, create WSGI-compatible routes for it, link it to the new Lambda function, and finally delete the archive from your S3 bucket. Handy!

Be aware that the default IAM role and policy created for executing Lambda applies a liberal set of permissions. These are most likely not appropriate for production deployment of important applications. See the section Custom AWS IAM Roles and Policies for Execution for more detail.

Updates

If your application has already been deployed and you only need to upload new Python code, but not touch the underlying routes, you can simply:

$ zappa update production
Updating..
Your application is now live at: https://7k6anj0k99.execute-api.us-east-1.amazonaws.com/production

This creates a new archive, uploads it to S3 and updates the Lambda function to use the new code, but doesn't touch the API Gateway routes.

Docker Workflows

In version 0.53.0, support was added to deploy & update Lambda functions using Docker.

You can specify an ECR image using the --docker-image-uri option to the zappa command on deploy and update. Zappa expects that the image is built and pushed to a Amazon ECR repository.

Deploy Example:

$ zappa deploy --docker-image-uri {AWS ACCOUNT ID}.dkr.ecr.{REGION}.amazonaws.com/{REPOSITORY NAME}:latest

Update Example:

$ zappa update --docker-image-uri {AWS ACCOUNT ID}.dkr.ecr.{REGION}.amazonaws.com/{REPOSITORY NAME}:latest

Refer to the blog post for more details about how to leverage this functionality, and when you may want to.

If you are using a custom Docker image for your Lambda runtime (e.g. if you want to use a newer version of Python that is not yet supported by Lambda out of the box) and you would like to bypass the Python version check, you can set an environment variable to do so:

$ export ZAPPA_RUNNING_IN_DOCKER=True

You can also add this to your Dockerfile like this:

ENV ZAPPA_RUNNING_IN_DOCKER=True

Rollback

You can also rollback the deployed code to a previous version by supplying the number of revisions to return to. For instance, to rollback to the version deployed 3 versions ago:

$ zappa rollback production -n 3

Scheduling

Zappa can be used to easily schedule functions to occur on regular intervals. This provides a much nicer, maintenance-free alternative to Celery! These functions will be packaged and deployed along with your app_function and called from the handler automatically. Just list your functions and the expression to schedule them using cron or rate syntax in your zappa_settings.json file:

{
    "production": {
       ...
       "events": [{
           "function": "your_module.your_function", // The function to execute
           "expression": "rate(1 minute)" // When to execute it (in cron or rate format)
       }],
       ...
    }
}

And then:

$ zappa schedule production

And now your function will execute every minute!

If you want to cancel these, you can simply use the unschedule command:

$ zappa unschedule production

And now your scheduled event rules are deleted.

See the example for more details.

Advanced Scheduling

Multiple Expressions

Sometimes a function needs multiple expressions to describe its schedule. To set multiple expressions, simply list your functions, and the list of expressions to schedule them using cron or rate syntax in your zappa_settings.json file:

{
    "production": {
       ...
       "events": [{
           "function": "your_module.your_function", // The function to execute
           "expressions": ["cron(0 20-23 ? * SUN-THU *)", "cron(0 0-8 ? * MON-FRI *)"] // When to execute it (in cron or rate format)
       }],
       ...
    }
}

This can be used to deal with issues arising from the UTC timezone crossing midnight during business hours in your local timezone.

It should be noted that overlapping expressions will not throw a warning, and should be checked for, to prevent duplicate triggering of functions.

Disabled Event

Sometimes an event should be scheduled, yet disabled. For example, perhaps an event should only run in your production environment, but not sandbox. You may still want to deploy it to sandbox to ensure there is no issue with your expression(s) before deploying to production.

In this case, you can disable it from running by setting enabled to false in the event definition:

{
    "sandbox": {
       ...
       "events": [{
           "function": "your_module.your_function", // The function to execute
           "expression": "rate(1