IaC Django Serverless Starter for AWS

This project demonstrates how to deploy a Django application utilizing a fully serverless architecture on AWS. It uses AWS Lambda as the execution environment, SQLite as the database, and CloudFormation/SAM for infrastructure provisioning. The setup includes a local development environment using VS Code and Docker/Devcontainer. Please note that this project is intended for demonstration purposes and is not suitable for production use (see Limitations section).

Table of Contents

1. Demo
2. Architecture
3. Installation
4. Usage
5. Limitations
6. License
7. Disclaimer

Demo

A simple Django polls application:

• Live Demo
• Admin Portal (read-only)
  • Username: demo
  • Password: djangoserverless

Architecture

This solution uses the following AWS services:

1. AWS Lambda
2. Amazon API Gateway
3. Amazon VPC
4. Amazon EFS
5. AWS CloudFormation
6. AWS SAM
7. Amazon CloudWatch

Overview

Database

The SQLite database file is stored on EFS, which is automatically mounted to every launched Lambda function.

HTTP & ASGI

This project uses the AWS Lambda Web Adapter as a bridge between Django's ASGI application and Amazon API Gateway.

Static Files

Static files are served from EFS by Lambda via an ASGI application blacknoise and API Gateway.

Advantages

This serverless approach offers several benefits:

1. Eliminates the need for running EC2/RDS instances.
2. Avoids leasing IPv4 addresses.
3. Can seamlessly scale down to zero.
4. Small projects can run almost entirely within AWS Free Tier limits.
5. High availability: the application is deployed across three availability zones.

Disadvantages

This approach has notable drawbacks primarily due to the use of SQLite in conjunction with network-attached storage:

1. Lack of support for concurrent writes: SQLite relies on file locking for database consistency, but Amazon EFS only supports advisory locking. Since read/write operations don't check for conflicting locks before executing, concurrent writes can lead to database corruption. This makes the setup unsuitable for multi-writer scenarios.

2. Relatively high latency: Even basic applications that perform database queries may experience latency exceeding 80 milliseconds with read requests and over 150 milliseconds with write requests.

3. Relatively slow cold start: Initial startup takes over 1 second, which may affect responsiveness and user experience, especially in time-sensitive applications.

Supported Versions

Python: 3.12

Django: 5.1

Installation

Prerequisites

Ensure the following are installed and configured:

1. Docker
2. VS Code
3. Dev Containers
4. AWS Account
5. AWS Credentials (Single-Sign On or Access Keys)

Launch Locally

1. Clone this repository:

git clone https://github.com/efficient-solutions/aws-iac-django-serverless-starter.git

2. Open the project in a Dev Container in VS Code.

3. Apply the Django database migration by running the following command in the VS Code terminal:

python src/manage.py migrate

4. Create a superuser by running the following command in the VS Code terminal:

python src/manage.py createsuperuser

5. Launch the Django application from the VS Code menu: Run > Run Without Debugging.

Usage

Build & Deploy

Before proceeding to the deployment, add your AWS credentials to the current environment. Then, execute the following commands in the VS Code terminal:

1. Build a deployment package

sam build

2. Deploy the stack and the application

sam deploy --guided

3. Apply the database migrations

sam remote invoke Function --event '{"manage":"migrate"}' --stack-name aws-iac-django-serverless-starter

4. Collect the static files

sam remote invoke Function --event '{"manage":"collectstatic"}' --stack-name aws-iac-django-serverless-starter

5. Create a superuser

sam remote invoke Function --event '{"manage":"create_superuser"}' --stack-name aws-iac-django-serverless-starter

This command creates a superuser root with a randomly-generated password which is returned in the output. Change this password once you log in. Also, this command can only be run once.

Launch Remotely

After successfully deploying, you will receive an HttpApiUrl output. Open this URL in your browser.

Due to the limitations of static serving from the Lambda function, it may take several minutes after running the collectstatic command before all static files are available. During this time, you may encounter occasional HTTP 404 errors.

Clean Up

To delete all the resources created within the stack, run the following command. This process can take over 5-10 minutes.

sam delete

Limitations

This project is intended for development and testing purposes only. It is not suitable for production due to the following limitations:

1. Concurrent writes can lead to database corruption.
2. Static files are served by Lambda, which is slow, resource-intensive, and potentially costly.
3. No option for handling media files.
4. No option for adding a custom domain.
5. No option for connecting to other AWS services or any external APIs from Lambda.
6. No option for database backup.
7. The /events endpoint, which handles non-HTTP events, is publicly accessible and unprotected.
8. Django's secret key is set with SAM CLI and insecurely stored in an environment variable.
9. Django's ALLOWED_HOSTS setting is configured with a wildcard by default, posing a security risk.

Production Use

For those considering this architecture for production environments, we recommend exploring our commercial version, which addresses all the limitations mentioned above.

License

This software is released under the GNU GPLv3 license.

Disclaimer

This software product is not affiliated with, endorsed by, or sponsored by Amazon Web Services (AWS) or Amazon.com, Inc. The use of the term "AWS" is solely for descriptive purposes to indicate that the software is compatible with AWS services. Amazon Web Services and AWS are trademarks of Amazon.com, Inc. or its affiliates.