Django, Docker and PostgreSQL Tutorial (2023)

• By Will Vincent
• December 8, 2022

In this tutorial we will create a new Django project using Docker and PostgreSQL. Django has built-in SQLite support, but even for local development it's best to use a "real" database like PostgreSQL that matches production.

Thispossibleto run PostgreSQL locally using a tool likepostgres.application, however, the preferred option among many developers today is to useStauer, a tool for creating isolated operating systems. The easiest way to think of it is as a large virtual environment containing everything needed for our Django project: dependencies, database, caching services, and all other necessary tools.

A major reason to use Docker is that it completely eliminates all configuration hassles when developing locally. Instead of worrying about what software packages are installed or running a local database with a project, just run a Docker image of the entire project. Best of all, this can be shared across groups and makes team building much easier.

Install Docker

The first step is to install the desktop Docker app on your local machine:

• docker for mac
• Dockers for Windows
• Docker for LinuxName

The initial Docker download may take some time. It's a big file. Feel free to stretch your legs at this point!

Once Docker has finished installing, we can confirm that the correct version is running. In your terminal, run the commandDocker-Version.

$ docker --version Docker-Version20.10.14, Build a224086

Compose dockeris an additional tool that is automatically included in Docker downloads for Mac and Windows. However, on Linux you have to add it manually. You can do this by running the commandsudo pip install docker-composeafter Docker installation is complete.

Hopefully the Docker installation is complete at this point. To confirm that the installation was successful, stop the local server withStrg+cand then writedocker start hello worldon the command line. You should see a response like this:

$ docker run hello-world Could not find image'Hello World: Latest'local latest: excerpt from library/hello-world7050e35b49f5: excerptCompletelySummary: sha256: 10d7d58d5ebd2a652f4d93fdd86da8f265f5318c6a73cc5b6a9798ff6d2b2e67 Status: Latest image downloadedProhello-world: Last Docker Hello! This message indicates that your installation appears to be working correctly. To generate this message, Docker took the following steps:1🇧🇷 The Docker client has contacted the Docker daemon.2🇧🇷 The Docker daemon extracted the"Hello World"Docker-Hub-Image.(brazo64v8) 3🇧🇷 The Docker daemon created a new container from this image that runs the executable that produces the output it's currently reading.4🇧🇷 The Docker daemon passed this result 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/ More examples and Ideas, visit: https://docs.docker.com/get-started/

Docker was successfully installed. We can proceed with setting up local Django and then switch to Docker and PostgreSQL.

Django configuration

The code for this project can be anywhere on your computer, but theMesaIt's an easy place to teach. From the command line, navigate to the desktop and create a new directory namedDjango-Docker.

# windowPS CD a ride\MesaPS mkdir Django-Stauer# MacOSPS CD ~/Mesa/CodePS mkdir Django-Stauer

We'll follow the standard steps to create a new Django project: create a dedicated virtual environment, start it, and install Django.

# windowPS Python -Metro venv .venvPS put down-execution policy -execution policy RemoteSigned -Reach current userPS .venv\scripts\activate.ps1(.venv) PS Python -Metro lump do not install pc Django~=4.0.0# MacOSPS Python3 -Metro venv .venvPS Those .venv/compartment/activate(.venv) PS Python3 -Metro lump do not install pc Django~=4.0.0

Then we can create a new project calleddjango_project,emigrateour database to initialize and useruntime serverto start the local server. I usually don't recommend walkingemigratein new projects untilafter thisA custom user model has been set up, but we'll ignore that advice in this tutorial.

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

Confirm everything worked by navigating tohttp://127.0.0.1:8000/in your browser. You may need to refresh the page, but you should see the familiar Django welcome page.

The final step before moving to Docker is to create aRequirements.txtFile containing the content of our current virtual environment. We can do this with a one-line command.

(.venv) $ pip freeze > requirements.txt

In your text editor, check the newly createdRequirements.txtoffice hours.

asgiref==3.5.0Django==4.0.4sqlparse==0.4.2

must containDjangoas well as the packagesAsgirefjsqlparsewhich are automatically included when Django is installed.

Now it's time to switch to Docker. Leave our virtual environment as we no longer need it by typingdeactivatejHand back.

(.venv) Disable $PS

How do we know that the virtual environment is no longer active? The directory name is no longer enclosed in parentheses on the command line. Any normal Django commands you try to run at this point will fail. Try it for examplemanage.py Python runtime serverto see what happens

PS Python tut.py runtime serverfile, file "/Usuarios/wsv/Desktop/django-docker/manage.py", line 11, no principal from ... to django.core.management import run_from_the_command_lineModule not found error: not Module called 'Django'

With that we are completely out of the virtual environment and ready for Docker.

dockable image

a dock workerPhotois a read-only template that describes how to build a DockerContainer🇧🇷 The image is the instructions while the container is the actual running instance of an image. To continue our dwelling analogy from the beginning of the chapter, a picture is the blueprint, or set of blueprints, for the construction of a dwelling; The container is the actual building, already built.

Images are usually based on another image with some additional adjustments. For example, there is a long list of officially supported images forPythondepending on the desired Python version and flavor.

Dockerfile

For our Django project, we need to create a custom image that includes Python, but also installs our code and contains additional configuration details. To create our own image, we create a special file calledDockerfilewhich defines the steps to build and run the custom image.

Use your text editor to create a new one.DockerfileFile in the project-level directory next to thegestionar.pyProcess. In it, add the following code, which we will see line by line below.

# Throw Base PhotoFROM ... TO Python:3.10.2-delgado-Diana# put down Vicinity variablesENV PIP_DISABLE_PIP_VERSION_CHECK 1ENV PYTHONDONWRITEBYTECODE 1ENV Python without search 1# put down work directoryWORK MANAGER /Code# To install dependenciesCOPY ./Requirement.TXT .RUN lump do not install pc -r Requirement.TXT# Copy ProjectCOPY . .

DockerfileEmails are read from top to bottom when an image is created. The first statement is aFROM ... TOCommand that tells Docker which base image we want to use for our application. Docker images can inherit from other images. So instead of building our own base image, we'll use the official Python image that already contains all the necessary tools and packages for our Django application. In this case we use Python3.10.2and the much smaller onesdelgadoVariant that does not contain the general packages contained in the standard tag. The labelDianarefers to the latest stable version of Debian. It's a good idea to set this explicitly to minimize potential outages when there are new versions of Debian.

So we use thoseENVCommand to set three environment variables:

• PIP_DISABLE_PIP_VERSION_CHECKdisables an automatic check oflumpalways updated
• PYTHONDONWRITEBYTECODEmeans Python will not try to write.pycrecords
• Python without searchensures that our console output is not buffered by Docker

The commandWORK MANAGERIt's used to set a default working directory when running the rest of our commands. This tells Docker to use this path as the default location for all subsequent commands. As a result, we can use relative paths based on the working directory instead of writing the full file path each time. In our case is the working directory/Codebut it can often be much longer and something like that/application/source,/usr/src/application, or similar variations depending on the specific needs of a project.

The next step is to install our dependencies withlumpit's himRequirements.txtfile that we have already created. OCOPYThe command takes two parameters: the first parameter tells Docker what files to copy into the image, and the second parameter tells Docker where to copy the files to. In this case we copy the existing one.Requirements.txtFile from our local computer in the current working directory, represented by..

once theRequirements.txtThe file is in the image, we can use our last command,RUN, accordingInstall pipe🇧🇷 This works exactly as if we were walkingInstall pipelocally on our machine, but this time the modules will be installed in the image. O-rflag sayslumpto open a file - calledRequirements.txthere - and install the content. If we don't include-rBanderalumpI would try and not be able to installRequirements.txtas it is not a real Python package.

At the moment we have a new image based on thethin targetvariant ofPython 3.10.2and install our dependencies. The final step is to copy all files from our current directory to the image's working directory. We can do this with thatCOPYDomain. Remember that two parameters are required, so we copy the current directory to our local file system (.) in the working directory (.) of the picture.

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

.dockerignore

ONE.dockerignorefile is a recommended way to specify specific files and directories that should not be included in a Docker image. This can help reduce the overall size of the image and improve security by keeping things that need to be kept secret outside of Docker.

For now, we can safely ignore the local virtual environment (.venv), the future.gitDirectory and a future.ignore.gitProcess. In your text editor, create a new file named.dockerignorein the base directory next to the existing onegestionar.pyoffice hours.

.venv.git.ignore.git

We now have our full instructions for creating a custom image, but we haven't created it yet. The command to do so is not surprising.Docker-Buildfollowed by the period., recalling theDockerfileis in the current directory. A lot is produced here. I only included the first two lines and the last one.

PS Stauer accumulate .[+] building 9.1s (10/10) TO LOCK => [intern] invoice accumulate Definition from ... to Dockerfile...=> => Write Photo sha256:89digitando1...

docker-compose.yml

Our fully built custom image is now ready to run as a container. To run the container, we need a list of instructions in a file calleddocker-compose.yml🇧🇷 Create one with your text editordocker-compose.ymlFile in the project-level directory next to theDockerfile🇧🇷 It contains the following code.

Version: "3.9"Services:Network:collect: .Ports:- "8000:8000"Command: Python runtime server manage.py 0.0.0.0:8000Volume:- .:/code

In the top line we define theLast versionfrom Docker Compose, which is currently3.9🇧🇷 Then we determine which onesServices(or containers) that we want to run in our docker host. It is possible to have severalServicesrunning, but at the moment we only have one fornetwork.

Insidenetworkwe determineaccumulateto browse the current directory of ourDockerfile🇧🇷 We use Django's default ports8000and run itDomainto run the local web server. Finally, thatvolumesmount automatically synchronizes the Docker file system with our local computer's file system. So when we make a change to the code in Docker, it's automatically synced to the local file system.

The last step is to run our docker container with the commanddocker-compose🇧🇷 This command results in another long stream of output code on the command line.

PS Stauer-compose until[+] building 4.2s (10/10) TO LOCK  => [intern] invoice accumulate Definition from ... to DockerfileStep 1/7 : FROM ... TO Python:3.10...attach one Stauer-network-1Stauer-network-1 | Search Pro office hours changes impostor Stat-ReloaderStauer-network-1 | Run System reviews...Stauer-network-1 |Stauer-network-1 | System To verify identified Not questions (0 muted).Stauer-network-1 | march 22, 2022 - 21:51:04Stauer-network-1 | Django execution 4.0.4, use The definition 'django_project.settings'Stauer-network-1 | Von in development Server no http://0.0.0.0:8000/Stauer-network-1 | Leave a Server impostor CHECK-C.

To confirm that it really worked, try again.http://127.0.0.1:8000/in your browser. Refresh the page and the Hello, World page should still appear.

Django now runs exclusively in a Docker container. We do not work in a virtual on-site environment. We don't operate thatruntime serverDomain. All of our code is now in place and our Django server is running in a standalone Docker container. Success!

We will create a number of Docker images and containers in this book, and with practice the flow will make more sense:

• create aDockerfilewith custom picture instructions
• add a.dockerignoreoffice hours
• build image
• create adocker-compose.ymloffice hours
• Rotate container

Stop the currently running container withStrg+c(Press the "Control" and "c" keys at the same time) and also typedocker-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 need to be stateless, which is why we usevolumesto copy our code locally where it can be saved.

$ docker-compose down[+]To run2/2 ⠿ Container docker-web-1 removed ⠿ Network docker_default $

Whenever new technology is introduced, there are potential security issues. In the case of Docker, an example is that it defines the default user asThose🇧🇷 🇧🇷 🇧🇷 🇧🇷 The root user (also known as "superuser" or "administrator") is a special user account used in Linux for system administration. He is the most privileged user on a Linux system and has access to all commands and files.

The Docker documentation has a section, a large section on security and specifically onModo enraizadoTo avoid it. We won't cover that here as this is a book about Django, not Docker, but especially if your site stores sensitive information, read the entire security section carefully before posting anything.

psychopg2

It's important to stop now and think about what it means to install a package on Docker instead of in a local virtual environment. In a traditional project, we would run the commandpython -m pip installs psycopg2-binary==2.9.3on the command line to install Pyscopg2. But now we work with Docker.

There are two possibilities. The first thing to installpsycopg2 binarylocal and thenFreeze nuggetsupdate our virtual environmentRequirements.txt🇧🇷 If we were to use the local environment, this might make sense. But since we're committed to Docker, we can skip this step and just update insteadRequirements.txtwith himpsycopg2 binaryPackage. We no longer need to update the real virtual environment as we probably won't be using it. And if we ever did, we can update it based onRequirements.txtDespite it.

In your text editor, open the existing oneRequirements.txtarchive and addpsycopg2-binary==2.9.3to the floor.

asgiref==3.5.0Django==4.0.4sqlparse==0.4.2psycopg2-binary==2.9.3

At the end of our PostgreSQL configuration changes, we will build the new image and activate our containers. But not yet.

postgresql

not existentdocker-compose.ymlFile add a new service calledDatabase🇧🇷 This means that there are two separate containers running inside our docker host:networkto the local Django server andDatabasefor our PostgreSQL database.

ÖnetworkThe service depends on itDatabaseservice is running, we add a line with the namedepends ononenetworkit means.

InsideDatabaseservice we specify which version of PostgreSQL to use. At the time of writing this article, Heroku supports the version13than the latest version, so we will use that one. Docker containers are ephemeral, which means all information is lost when the container stops working. This would of course be a problem for our database! The solution is to create onevolumesnamed assemblypostgres_dataand then map it to a dedicated directory inside the container at the location/var/lib/postgresql/datos/🇧🇷 The final step is to add aauthentication trustAllVicinitytoDatabase🇧🇷 For large databases with many database users, it's a good idea to be more explicit about permissions, but this setting is a good choice when there's only one developer.

The updated file looks like this:

execution: "3,9"Services: network: accumulate: . Domain: Python /Code/tut.py runtime server 0.0.0.0:8000 volumes: - .:/Code doors: - 8000:8000 depends on: - Database Database: Photo: postgr:13 volumes: - postgres_data:/war/Start/postgresql/Dice/ Vicinity: - "POSTGRES_HOST_AUTH_METHOD=confiar"volumes: postgres_data:

DATABASE

The third and final step is updating theproject_django/configurations.pyFile to use PostgreSQL and not SQLite. In your text editor, scroll down toDATABASEcontext

By default, Django specifiessqlite3as the database engine, give it the namedb.sqlite3, and plug it inBASE_DIRthat is, in our directory at the project level.

# django_project/settings.pyDATABASE = { "Imperfection": { "MOTOR": "django.db.backends.sqlite3", "NAME": BASE_DIR / "db.sqlite3", }}

To move to PostgreSQL, we update theMOTORKontext. PostgreSQL erfordert aNAME,USERNAME,CLAVE,HOST, YouPorto🇧🇷 For the sake of simplicity, we define the first three inpostgr, aHOSToneDatabaseWhat is the name of our service based indocker-compose.yml, it's himPortoone5432Was ist Standard-PostgreSQL?Porto.

# django_project/settings.pyDATABASES = {"imperfection": {"MOTOR": "django.db.backends.postgresql","NAME": "postgres","USER": "postgres","PASSWORT": "postgres","HOST": "db", # defined in docker-compose.yml"PORT": 5432, # Standard-Postgres-Port}}

And this is! We can contain our new imagepsycopg2 binaryand rotate the two containers in separate mode with the following single command:

$ docker-compose -d --build

If you update the Django welcome page inhttp://127.0.0.1:8000/It should work, which means Django has successfully connected to PostgreSQL via Docker.

Running commands in Docker is a little different than a traditional Django project. for example foremigrateIn the new PostgreSQL database running on Docker, run the following command:

$ docker-composeexecutiveMigrate web python manage.py

if you wanted to runCreate superuserYou would also prepend it withdocker-compose exec web...as soon:

$ docker-composeexecutiveCreate the superuser web python manage.py

Etc. When you're done, don't forget to close the docker container as it can consume a lot of computer memory.

$ docker-compose down

quick check

Here is a short version of the terms and concepts we covered in this post:

• Photo: the "definition" of your project
• Container: where your project is actually running (an instance of the image)
• Dockerfile: Set the appearance of your image
• docker-compose.yml: oneYAMLfile that takes the Dockerfile and adds additional instructions on how our docker container should behave in production

we use thatDockerfileTell Docker how to build oursPhoto🇧🇷 We then carry out our actual project within aContainer. Ödocker-compose.ymlThe file contains additional information about how our Docker container should behave in production.

Next Steps

If you're interested in learning more about using Django, Docker, and PostgreSQL, I've written an entire book on the subject.Django for professionals🇧🇷 The first chapters can be read online for free.