This directory contains cookiecutters for the containerization of web applications.
Clone this repository to your favorite working directory –
git clone https://github.com/datamade/how-to.git && cd how-to/docker/templates– and build or update your template image.
docker-compose buildTo run cookiecutter on a specific template, you can run cookiecutter -f path/to/template/dir.
So, to generate a new Django project, use Docker to run cookiecutter with the new-django-app/ directory
as a target:
docker-compose run --rm cookiecutter -f new-django-appTo generate a Docker environment for an existing Python project, use the
python-docker-env directory as a target:
docker-compose run --rm cookiecutter -f python-docker-envWhen you run cookiecutter, it will ask you to define some or all of the following variables
in your terminal:
| Variable | Definition |
|---|---|
directory_name |
The directory that will contain your generated files. We'll move the files out and remove this directory after running cookiecutter so it's fine to use the default here. |
app_name |
The slug you use to refer to your application (typically the same as the GitHub repo). |
app_verbose_name |
A verbose name for your application, written in plain English and typically title-case (e.g. "BGA Pensions Database"). |
module_name |
The slug you use to refer to the Python module that contains your app. In contrast to app_name, this variable must be a valid Python module name, e.g. underscores are permitted while spaces/hyphens are not. |
local_settings |
If your project includes a local settings file, set this equal to the relative path to your local settings file (or your example settings file, if it includes working values), and it will be automatically mounted into your application container. Set this to the string None if your application does not use a local settings file. |
run_command |
The command to run your application. |
migrate_command |
The command to migrate your database. |
auto_migrate |
Whether your database migration should be run every time you start your application. Set this to False if you have a workflow that involves loading in a database dump. Note that you will need to run migrations manually thereafter, e.g., docker-compose exec app python manage.py migrate. |
postgis |
Whether to use the Postgis image. |
pg_version |
The version of the Postgres or Postgis image you'd like to use. |
pg_db |
The name of your database. |
Once you've generated your files, you'll need to move them out of the how-to/docker/templates
directory and into whatever repo needs to use them.
If you're generating a Django app using the new-django-app template, typically you'll
need to move the new directory you generated to be a sibling of the how-to
directory (i.e. move it to wherever you store your DataMade projects). Then, change
into the new directory and initialize it as a Git repo with git init:
# Replace ${directory_name} with the name of the directory you just set
# If you used the default, it's my-new-app
mv ${directory_name} ../../..
cd ../../../${directory_name} && git initIf you're generating a Docker environment for an existing
app using the python-docker-env template, you'll need to move the files you generated to
the repo that stores the existing project. For example:
# Replace ${directory_name} with the name of the directory you just set
# If you used the default, it's my-docker-env
rsync -av ${directory_name}/* /path/to/existing/project && rm -rf ${directory_name}/Note that this will preserve configs/ and scripts/ directories and their
contents, if your project already contains them.
The templated configs were written to serve our most common use cases. Sometimes, though, your deployment may require changes or additions to the boilerplate files. Perhaps you need to mount additional volumes in your Docker config, or define an extra service, e.g., Redis for queueing or Solr for search.
For Django apps produced with the new-django-app template, you'll always want to at least
pin the requirements in requirements.txt to the latest available versions. We
recommend pip chill for this task:
# Run this on your host machine to spawn a shell in an app container
$ docker-compose run --rm app bash
# Run this inside the spawned app container
~ pip-chill | grep -v pip-chill > requirements.txtYou may need to make other adjustments; refer to the Django docs for more on project setup.
If you need to make a customization and aren't sure how to start, check in with a Lead Developer. Chances are we've made that customization before and can refer you to an example project.
It's easy to use Sass to override Bootstrap styles, but there are a few places where you'll need to set up scripts and imports. These can be easy to miss, making this process tricky to debug, so here's a list of items to make sure you add to your code as you're trying to style over Bootstrap:
- Import bootstrap styles at the bottom of your Sass file, like [here](https://github.com/datamade/california-dream-index/blob/dbc90bc7ae6b7cb5c5af65e0f8224f5361039965/cdi/static/scss/custom.scss#L63)
- Include Bootstrap in your [`package.json` file](https://github.com/datamade/california-dream-index/blob/dbc90bc7ae6b7cb5c5af65e0f8224f5361039965/package.json#L13). Don't forget to add the development script at the bottom! This will compile your changes as you make them.
Check out the Bootstrap documentation for information on how to start overriding Bootstrap styles using Sass.
For current examples see our California Dream Index repo and our CRP Microsote repo
Change to your application directory, run docker-compose up -d to build your
application and its services, then go to localhost:8000 (or whatever port you defined
in the run command) to view your containerized app.
See Using your docker-compose setup
for more on local development with Docker.