A Django + Vue reference project that focuses on developer tooling and CI/CD + IaC
Project Documentation: https://briancaffey.github.io/django-step-by-step/
This is a Django reference project showing how to develop and deploy Django applications using multiple tools and methodologies with best practices and concise examples.
This project implements a simple blog app using vanilla Django function-based views and class-based views as well as DRF function and class-based views. There is also an implementation of the same application using GraphQL. The application involves a simple data model including users, posts with text and image and post likes. Local development using virtual environments and docker are both covered in detail, including guidance on how to run the application on different operating systems (Linux, Intel Mac, M1 Mac, Windows, WSL). There is 100% test coverage for the project and comprehensive e2e tests using Cypress.
Deployment to AWS environment on Elastic Container Service (ECS) is shown with both:
terraform-aws-django
This project is originally designed as a reference or example project that I can use when I need to recall common patterns, syntax and frequently-used code snippets. I have tried to carefully document each part of the development process as a guide for someone who wants to learn how this project is built and deployed from the ground up. Please visit the project documentation site (briancaffey.github.io/django-step-by-step/) for a complete explanation of the project, step-by-step.
This project is open-source and newcomers to Django and Python and welcome to create issues and pull requests.
This project implements a simple microblogging application called μblog. Here are some of the core features of μblog:
μblog's core microblogging application is implemented in 5 different ways:
Each implementation is tested and documented with OpenAPI (Swagger UI). GraphiQL is exposed for the GraphQL API which includes documentation for queries and mutations.
Django templates and Bootstrap are used for the function and class based Django views. Vue.js is used to implement the like button using AJAX (with axios).
This project is heavily focused on the process of setting up the development environment. This project has been tested and developed on:
Windows 10 PowerShell development environment is still WIP. Here are some important features of the local development environment:
A Makefile is included in the root of the project to document. This file helps to document each step of the local development environment and deployment process.
This project's Python dependencies are managed with poetry. Poetry dependencies and dev-dependencies are specified in pyproject.toml
. These dependencies are exported to two files:
requirements.txt
: This contains only the dependencies that are required by the project for running in productionrequirements_dev.txt
: This contains all the dependencies that are required for running in production and for local developmentThe application can be developed with a virtual environment locally. This requires starting postgres and redis services locally. Alternatively, postgres, redis and other supporting services can be started with a docker-compose file that exposes the services on localhost
.
Docker is a popular choice for developing and deploying applications, including Django. docker-compose can be used to run the application and dependent services in containers. See docker-compose.yml
in the root directory for more details.
The docker-compose file contains the following services:
The application can also run locally inside a local Kubernetes cluster. This is made possible with minikube. cdk8s and pulumi are both used to show how kubernetes manifest files can be generated dynamically from code (TypeScript) and deployed to a cluster.
Cypress is used for e2e testing which can run locally against the docker-compose development environment. To test user registration and email verification in e2e tests, MailHog and the MailHog API are used to retrieve the email confirmation link from the email sent by the Django application.
Multiple tools are used for running unit tests and code quality checks on each commit. These include:
Continuous integration checks that all unit tests pass and that code is formatted correctly. Unit tests run the Python code in a simulated environment that contains the dependent services (postgres and redis). The following tools are used in CI:
This project focuses on deployment to AWS using Elastic Container Service.
ECS is my preferred way of running containerized web applications on AWS. To help document best practices for deploying Django applications on ECS, I wrote a reusable CDK construct library that handles infrastructure provisioning for typical deployment scenarios. This project can be found here.
The Django ECS construct included in the library creates the following AWS resources:
The Django ECS construct takes a few inputs, including:
This project can deploy ECS from the command line (using make cdk-deploy
) or from a CI/CD pipeline. GitHub Actions and GitLab CI both include pipeline stages that deploy the application to AWS ECS.
Additional ECS Exec is used to run management commands and open shells inside of the containers running on Fargate.
See LICENSE.md
This project tries to follow the 12 Factor App principles. Here are the 12 factors of the 12 Factor app with a brief description of how they are achieved in this project across multiple deployment environments.
The code can be found in multiple public repositories:
One codebase tracked in revision control, many deploys
There are a few different ways in which this project manages dependencies:
poetry
manages Python dependenciesnpm
manages TypeScript/JavaScript dependencies for the construct library applicationDockerfile
defines dependencies needed for the container, including the version of Python to usedjango-cdk
library defines specific version of AWS services to use, such as the version of postgres and Redis that are usedterraform-aws-django
also defines specific versions, such as the database engine version to use for PostgresThere is a good amount of environment variables used for configuration both locally and in the different production environments.
Locally, the application uses default values that allow development in a virtual environment to work without the need for configuring any environment variables as a separate step.
For example, Postgres is configured with the following default values in the Django application:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql_psycopg2",
"NAME": os.environ.get("POSTGRES_NAME", "postgres"),
"USER": os.environ.get("POSTGRES_USERNAME", "postgres"),
"PASSWORD": os.environ.get("POSTGRES_PASSWORD", "postgres"),
"HOST": os.environ.get("POSTGRES_SERVICE_HOST", "localhost"),
"PORT": os.environ.get("POSTGRES_SERVICE_PORT", 5432),
}
}
The django-cdk
application uses environment variables to determine which options to use for deployment. For example, the HostedZoneName
is read in from the environment and use to determine which DNS records and ACM records to create. CloudFormation Stacks help to isolate environments, and no infrastructure is shared between environments.
A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials.
This is another important point from the 12 Factor App principles that is true for this project.
One interesting part about config is the Postgres password for the ECS environment. The ECS environment uses an AWS Secrets Manager Secret
to store the database password information, including the password, in a JSON string.
The name of this Secret
is passed as an environment to the Django application, and the Django application uses another library to retrieve and cache the database password for later use. Again, the value of the secret is not passed to Django as an environment variable, but the name of the Secret
(from AWS Secrets Manager) is the value passed. This way we don't even have to worry about what the password is. It is not stored in the code base and it is not even stored anywhere in config (until is created in AWS Secrets Manager).
In AWS, it is easy to start relying on AWS services such as RDS, ElastiCache, S3 and other services.
This step in the 12 Factor App is where CDK really shines. The cdk deploy
command builds, releases and runs the application in one command. First, it is important to note that CDK uses something called DockerImageAsset
, which allows us to point to the directory and Dockerfile of an application that we want to build and push to a docker registry. To use this feature, we must first run cdk bootstrap
once in our AWS account. This will create the ECR registry that any DockerImageAsset
will be pushed to.
When cdk deploy
runs, it first builds and pushes the docker image to the ECR registry created by the cdk bootstrap
command. cdk deploy
then proceeds to create or update the AWS resources defined in the construct. Another advantage of CDK is automatic rollbacks.
Execute the app as one or more stateless processes
In each environment, both local and non-local, the application's processes are clearly defined.
The CDK construct is passed a list of strings that define the processes that are run in the container for the wep services as well as the celery worker and celery beat processes.
This is done in ECS.
The array of process types and number of processes of each type is known as the process formation.
The ECS construct has a simple process formation: web service that scales up and down between a minimum and maximum number of instances. Celery workers that scale between a minimum and maximum number of instances, and a single celery beat process.
Using CDK is a great way to put application disposability into practice. ECS services make sure that some number of ECS Tasks are running at a given point in time. If we go into the AWS console and delete a task, it will be started again almost instantly.
This project makes dev/prod parity somewhat trivial. Using Infrastructure as Code, we can be confident that two environments will only vary by the values that are passed in through environment variables. If the only difference between two application stacks is the subdomain, then we can expect that everything else about the two applications is similar and that none of the other resources between the two environments will be shared.
CloudWatch is a great tool for monitoring logs and getting observability with minimal effort.
Run admin/management tasks as one-off processes
Developers will often wish to do one-off administrative or maintenance tasks for the app, such as:
With ECS and CDK, management commands can be run easily either through automation or using a tool called ECS Exec.
To run automated tasks, managementCommandProps
can be passed a value of true
(false
by default). This will run the task each time the application is deployed with cdk deploy
. This uses the AWS Custom Resource that is defined in the construct. The CR's onCreate
and unUpdate
are set to an AwsSdkCall
that runs ecs:RunTask
with the appropriate parameters.
If you do not want to run database migrations automatically as a Custom Resource in CDK, you can use the AWS CLI to run the command from your CI tool, or you can use ECS Exec.
ECS Exec would also be a good choice if you want to run a one-time script or open a console in the container.
Backend tests for the Django application run when code is pushed to the dev
branch.