A dockerized Django development environment for quick project starts.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


gypsy - a Dockerized Django Development Environment

Gypsy is an attempt to bring a production-like environment to a local development machine to facilitate complete holistic development, focused around a modular system of bash scripts that glue together Docker, Docker-Compose, Git, and a few other system tools.

Gypsy is very much the product of having seen what can go right and wrong inside development environments, and particularly other docker based approaches. This proof-of-concept was developed on OSX, and as such was only ever intended to work on OSX and Linux (sorry Windows users).


You'll need the following installed on your dev machine:

  • bash
  • docker
  • docker-compose
  • python (to interact with the venv shell)

Quick Start

The ./gypsy command allows you to interact with the development environment.

To build the project and get up and running: ./gypsy environment local (To select local as the operating environment.) ./gypsy start (To build and start the project)

You should then be able to open a web browser and visit http://localhost:8000 and open the code folder in your favorite ide.


Gypsy has a fairly opinionated architecture installed by default. The components are listed here: Architecture

Most of the containers are accessible via ports mapped to the host machine. The containers use shortform names to facilitate communication between them: Network


Environment Definitions

All environment data is stored in code/environments. You'll be able to customize docker-compose files for each environment by editing them here. On launch, the docker-compose file for the active environment is symlinked to code/docker where it becomes active.

'Bouncable' Containers

Some containers need their processes to be restarted during code changes. Marking a container as bouncable ensures it will be rebuilt and restarted during the ./gypsy start command. I'm still evaluating the best way to control this behavior, but for now the solution is to add the container name to code/docker/bounce.list to ensure it is restarted on request.

Managing Secrets in the Development Context

./gypsy blob allows you to create an encrypted credential store you can use in a non-production setting to store secrets that will be injected into Vault. (Typically in production you would have an actual Vault server that already holds all secure credentials.) This blob file is re-encrypted with a one-time-password each time you start a project or edit the blob file.

Vault is populated via a vault-seed.sh script found in each environment's content folder. Normally in production and staging you would not be reseeding vault on a regular basis, so you would likely remove this component and modify the bootstrap.sh to avoid calling it.

The Gypsy Cache

Gypsy caches some information about your environment between sessions in the gypsy.cache folder, it's fairly harmless to delete this folder- but make sure you backup your blob file first.


Gypsy flags are a simple method for setting startup conditions that can be triggered on container start up. On startup the django container will execute the script code/docker/django/bootstrap.sh. Conditional checks for the presence of flags in this script is a simple way to control startup execution.