Quick-start Guide for a Dockerized Django Project

Summary:

Fundamentals of Docker and why we use containers
Create custom images using Dockerfiles
Create a basic Django project and additional Django applications

Prerequisites

Install Docker Desktop
- Has support for Windows and MacOS

1. Creating a custom Docker image

Create Dockerfile

Start by making a file called Dockerfile in a new project folder with the following contents:

FROM python:3
ENV PYTHONUNBUFFERED 1

RUN mkdir /app
WORKDIR /app
COPY requirements.txt /app/
RUN pip install -r requirements.txt
COPY . /app/

Create requirements.txt

Additionally, create a requirements.txt specifying that we need Django 3 in our project:

Django>=3.0

Build custom image

This builds the custom image so that can create containers based off of it. Run this in your project root folder:

docker build -t [IMAGE_NAME] .

The . tells Docker to try to find a Dockerfile in the current directory which we made earlier. If all goes well, you should see some output showing your image being built.

Note: You can also run docker-compose build to build an image for every service specified.

2. Initializing the Django project

Start the container using the Docker image

This is so we have access to a version of Django, which is installed inside our container.

docker run -it -v [LOCAL_PROJECT_DIRECTORY]:/app [IMAGE_NAME] bash

Notes:

The -it flag is required when using any interactive command such as bash.
The -v flag is used to bind some local volume on our computer (~/Desktop/project) to one in our container (/app).
The next argument specifies the image to use when making our container.
The last argument is the command we want to execute in our new container - in this case, bash so we can have a shell to execute commands in inside our container.

Run the command to initialize the Django project.

django-admin startproject [PROJECT_NAME] .

If all went well, there should be a new folder called [PROJECT_NAME] both inside the container and in the local project folder!

(Optional) Add more applications to your Django project

python manage.py startapp [APP_NAME]

This will create a new application directory within your project with the following layout:

[APP_NAME]/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

Exit the container at any time using exit or Control+D. If you need to open a bash shell inside the container again, exec into the (running) container:

docker exec -it [CONTAINER_ID] /bin/bash

The container ID can be found in the list of containers on your machine using docker ps -a.

Or, exec using docker-compose:

docker-compose exec [SERVICE_NAME] bash

The service name is any service listed in your docker-compose.yml file (ex. web, db, etc). For more information on docker-compose, see section 3 below.

3. Running the Django application (locally)

Method 1: Start app using vanilla Docker:

docker run -it -v ~/Desktop/week2-example:/app deploy-week2 bash
root@ec54217e493c:/app# python manage.py runserver 0.0.0.0:8000

Note: If http://localhost:8000 will not load, this may be because we haven't exposed any ports on our container to our local machine. We could do this by adding the flag -p 8000:8000, but...

Method 2: docker-compose

Create a docker-compose.yml in your project with the following contents:

version: '3'

services:
  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - '8000:8000'

This is doing a couple of things:

Defining a service for our app - in this case, one that runs Django. Later on we'll have multiple services in the same app.
Specifying the Dockerfile to use for building. The . just means to look for it in the same directory.
Defining the command to use when running our service. This is the same Django command we used earlier.
Creating a volume mount between our local machine and our container.
Defining the port binding between our local machine and container. In this case, port 8000 in our container corresponds to port 8000 on our local machine.

Start the app with `docker-compose up`

Add the -d flag after this command to run services in detached mode (in the background). To re-attach to the services and view their logs, run docker-compose logs -f.

To stop all running compose containers (in this case just one), run docker-compose down.

Viewing your project

If everything worked as expected, you should be greeted with the following page at http://localhost:8000:

j-alicia-long/README.md