$ docker --version
Docker version 24.0.5, build ced0996

$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
70f5ac315c5a: Pull complete 
Digest: sha256:4f53e2564790c8e7856ec08e384732aa38dc43c52f02952483e3f003afbf23db
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

# Windows
$ cd onedrive\desktop
$ mkdir django-docker

# macOS
$ cd ~/desktop/code
$ mkdir django-docker

# Windows
$ python -m venv .venv
$ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
$ .venv\Scripts\Activate.ps1
(.venv) $ python -m pip install django~=4.2.0

# macOS
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python3 -m pip install django~=4.2.0

(.venv) $ django-admin startproject django_project .
(.venv) $ python manage.py migrate
(.venv) $ python manage.py runserver

(.venv) $ pip freeze > requirements.txt

asgiref==3.7.2
Django==4.2.5
sqlparse==0.4.4

(.venv) $ deactivate
$

$ python manage.py runserver
File "/Users/wsv/Desktop/django-docker/manage.py", line 11, in main
  from django.core.management import execute_from_command_line
ModuleNotFoundError: No module named 'django'

`Dockerfile's are read from top-to-bottom when an image is created. The first instruction is a `FROM` command that tells Docker what base image we want to use for our application. Docker images can be inherited from other images, so instead of creating our base image, we'll use the official Python image with all the tools and packages we need for our Django application. In this case, we're using Python `3.10.2` and the much smaller in size `slim` variant that does not contain the common packages contained in the default tag. The tag `bullseye` refers to the latest stable Debian release. Set this explicitly to minimize potential breakage when there are new releases of Debian.

Then, we use the `ENV` command to set three environment variables:

- `PIP_DISABLE_PIP_VERSION_CHECK` turns off an automatic check for `pip` updates each time
- `PYTHONDONTWRITEBYTECODE` means Python will not try to write `.pyc` files
- `PYTHONUNBUFFERED` ensures Docker does not buffer our console output

The command `WORKDIR` sets a default working directory when running the rest of our commands. This working directory is used by Docker as the default location for all subsequent commands. As a result, we can use relative paths based on the working directory rather than typing out the full file path each time. In our case, the working directory is `/code,` but it can often be much longer and something like `/app/src`, `/usr/src/app`, or similar variations depending upon the specific needs of a project.

The next step is to install our dependencies with `pip` and the `requirements.txt` file we created. The `COPY` command takes two parameters: the first parameter tells Docker what file(s) to copy into the image, and the second parameter tells Docker where you want the file(s) to be copied to. In this case, we are copying the existing `requirements.txt` file from our local computer into the current working directory, which is represented by `.`.

Once the `requirements.txt` file is inside the image we can use our last command, `RUN`, to execute `pip install`. This command works exactly the same as if we were running `pip install` locally on our machine, but this time the modules are installed into the image. The `-r` flag tells `pip` to open a file--called `requirements.txt` here--and install its contents. If we did not include the `-r` flag `pip` would try and fail to install `requirements.txt` since it isn't itself an actual Python package.

At the moment, we have a new image based on the `slim-bullseye` variant of `Python 3.11.5` and have installed our dependencies. The final step is to copy all the files in our current directory into the working directory on the image. We can do this by using the `COPY` command. Remember it takes two parameters so we'll copy the current directory on our local filesystem (`.`) into the working directory (`.`) of the image.

If you're confused right now don't worry. Docker is a lot to absorb, but the good news is that the steps involved to "Dockerize" an existing project are very similar.

## .dockerignore

A `.dockerignore` file is a best practice way to specify certain files and directories that should not be included in a Docker image. This can help reduce overall image size and improve security by keeping things that are meant to be secret out of Docker.

We can safely ignore the local virtual environment (`.venv`), a future `.git` directory, and a future `.gitignore` file. In your text editor, create a new file called `.dockerignore` in the base directory next to the existing `manage.py` file.

We now have complete instructions for creating a custom image, but we haven't built it yet. The command to do this is `docker build` followed by the period, `.`, indicating the `Dockerfile` in the current directory. There will be a lot of output here. I've only included the first two lines and the last one.

## docker-compose.yml

Our fully built custom image is now available to run as a container. To run the container we need a list of instructions in a file called `docker-compose.yml`. Create a `docker-compose.yml` file with your text editor in the project-level directory next to the `Dockerfile`. It will contain the following code.

Docker recently switched away from [Compose V1](https://docs.docker.com/compose/compose-file/compose-versioning/) to [Compose V2](https://docs.docker.com/compose/compose-file/). To use V2, we specify which `services` (or containers) we want running within our Docker host. It's possible to have multiple `services` running, but we have one for `web` for now.

Within `web`, we set `build` to look in the current directory for our `Dockerfile`. We'll use the Django default ports of `8000` and execute the `command` to run the local web server. Finally, the [volumes](https://docs.docker.com/storage/volumes/) mount automatically syncs the Docker filesystem with our local computer's filesystem. If we change the code within Docker, it will automatically be synced with the local filesystem.

The final step is running our Docker container using the command `docker-compose up`, resulting in another long stream of output code on the command line.

To confirm it worked, return to `http://127.0.0.1:8000/` in your web browser. Refresh the page; the "Hello, World" page should still appear.

Django is now running purely within a Docker container. We are not working within a virtual environment locally. We did not execute the `runserver` command. Our code now exists, and our Django server runs within a self-contained Docker container. Success!

With practice, the flow will start to make more sense.:

- create a `Dockerfile` with custom image instructions
- add a `.dockerignore` file
- build the image
- create a `docker-compose.yml` file
- spin up the container(s)

Stop the currently running container with `Control+c` (press the "Control" and "c" button at the same time) and additionally type `docker-compose down`. Docker containers take up a lot of memory, so it's a good idea to stop them when you're done using them. Containers are meant to be stateless, so we use `volumes` to copy our code over locally, where it can be saved.

Whenever any new technology is introduced, there are potential security concerns. In Docker's case, one example is that it sets the default user to `root`. The root user (also known as the "superuser" or "admin") is a special user account used in Linux for system administration. It is the most privileged user on a Linux system and can access all commands and files. The Docker docs contain an extensive section on security and specfifically on [rootless mode](https://docs.docker.com/engine/security/rootless/). We will not be covering it here since this is a book on Django, not Docker, but if your website stores sensitive information, review the entire security section closely before going live.

## psycopg

It's important to pause right now and think about what it means to install a package into Docker instead of a local virtual environment. In a traditional project, we'd run the command `python -m pip install "psycopg[binary]"` from the command line to install Pyscopg. But we're working with Docker now.

There are two options. The first is to install `"psycopg[binary]"` locally and then `pip freeze` our virtual environment to update `requirements.txt`. If we were going to use the local environment, this might make sense. But since we are committed to Docker, we can skip that step and update `requirements.txt` with the `"psycopg[binary]" package instead. We don't need to update the actual virtual environment further because it is unlikely we will be using it. And if we ever did, we can update it based on `requirements.txt` anyway.

Open the existing `requirements.txt` file in your text editor and add `"psycopg[binary]" to the bottom.

We will build the new image and spin up our containers at the end of our PostgreSQL configuration changes. But not yet.

## PostgreSQL

In the existing `docker-compose.yml` file, add a new service called `db`, which means two separate containers will be running within our Docker host: `web` for the Django local server and `db` for our PostgreSQL database.

The `web` service depends on the `db` service to run, so we'll add a line called `depends_on` to `web` signifying this.

Within the `db` service, we specify which version of PostgreSQL to use. As of this writing, Heroku supports version `14` as the latest release, so that is what we will use. Docker containers are ephemeral, meaning all information is lost when the container stops running--an obvious problem for our database! The solution is to create a `volumes` mount called `postgres_data` and then bind it to a dedicated directory within the container at the location `/var/lib/postgresql/data/`. The final step is to add a [trust authentication](https://www.postgresql.org/docs/current/auth-trust.html) to the `environment` for the `db`. It is recommended to be more explicit with permissions for large databases with many database users, but this setting is a good choice when there is just one developer.

Here is what the updated file looks like:

## DATABASES

The third and final step is to update the `django_project/settings.py` file to use PostgreSQL and not SQLite. Within your text editor, scroll down to the `DATABASES` config.

By default, Django specifies `sqlite3` as the database engine, gives it the name `db.sqlite3`, and places it at `BASE_DIR` in our project-level directory.

```python
# django_project/settings.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

# django_project/settings.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "postgres",
        "USER": "postgres",
        "PASSWORD": "postgres",
        "HOST": "db",  # set in docker-compose.yml
        "PORT": 5432,  # default postgres port
    }
}

$ docker-compose up -d --build

$ docker-compose exec web python manage.py migrate

$ docker-compose exec web python manage.py createsuperuser

$ docker-compose down