Skip to content

Using Docker in Development

Pegasus optionally includes support for Docker during development. The Docker development setup can also be used as a foundation for deploying to containerized platforms. See our deployment page for more details.

You need to install Docker prior to setting up your environment.

Mac users have reported better performance on Docker using OrbStack, which is a Docker Desktop alternative optimized for performance.

Windows users may also need to install a 3rd-party package to run make commands. The easiest way to do that is via these instructions.

First set up your Pegasus project with Docker enabled and using Postgres as a database following the getting started guide.

Terminal window
cd {{ project_name }}
Terminal window
make init

This will spin up a database, web worker, celery worker, and Redis broker and create and run your database migrations.

Note: users of older versions of Windows may need to install “make” separately to use it. Alternatively, you can just inspect the Makefile in the repository and run the commands manually (e.g. docker compose up -d).

Visit http://localhost:8000/ in a browser and you should be up and running!

Pegasus ships with a self-documenting Makefile that will run common commands for you, including starting your containers, performing database operations, and building your front end.

You can run make to list helper functions, and you can view the source of the Makefile file in case you need to add to it or run any once-off commands.

Most of the commands you might need to run in your project will involve running something like:

Terminal window
docker compose exec <container> <command>

The Makefile has many example of these you can refer to if you need to run a specific command against a specific container.

The Docker configuration is primarily in docker-compose.yml.

Depending on your project settings, there are several containers that might be running. These are outlined in the table below:

Container NamePurposeIncluded
pgRuns Postgres (primary Database)Always
redisRuns Redis (Cache and Celery Broker)Always
webRuns DjangoAlways
viteRuns Vite (for CSS/JavaScript assets)If building with Vite
celeryRuns Celery (for background tasks)If Celery is enabled
frontendRuns the React Front EndIf the standalone front end is enabled

The docker environment sets environment variables using the included .env file.

The .env file is automatically ignored by git, so you can put any additional secrets there. It generally should not be checked into source control. You can instead add variables to .env.example to show what should be included.

The Python environment is run in the containers, which means you do not need to have your own local environment if you are always using Docker for development. Python requirements are automatically installed when the container builds.

However, keep in mind that if you go this route, you will need to run all commands inside the containers as per the instructions below.

Running commands on the server can be done using docker compose, by following the pattern used in the Makefile.

For example, to bootstrap Stripe subscriptions, run:

Terminal window
docker compose exec web python manage.py bootstrap_subscriptions

Or to promote a user to superuser, run:

Terminal window
docker compose exec web python manage.py promote_user_to_superuser [email protected]

You can also use the make manage command, passing in ARGS like so:

Terminal window
make manage ARGS='promote_user_to_superuser [email protected]'

You can add any commonly used commands you want to custom.mk for convenience.

If you add or modify anything in your requirements.in (and requirements.txt) files, you will have to rebuild your containers.

The easiest way to add new packages is to add them to requirements.in and then run:

Terminal window
make requirements

Which will rebuild your requirements.txt file, rebuild your Docker containers, and then restart your app with the latest dependencies.

You can use debug tools like pdb or ipdb by enabling service ports.

This can be done by running your web container with the following:

Terminal window
docker compose run --service-ports web

If you want to set up debugging with PyCharm, it’s recommended to follow this guide on the topic.

Some environments---especially on Windows---can have trouble finding the files on your local machine. This will often show up as an error like this when starting your app:

python: can't open file '/code/manage.py': [Errno 2] No such file or directory

These issues are usually related to your disk setup. For example, mounting your code on a remote filesystem or external drive to your machine. To fix, try running the code on the same drive where Docker Desktop is installed, or on your machine’s default “C:” drive.

You can also get around this issue by running your application natively, instead of with Docker.