Document the interface between the deploy system and the deployed Django project

[dpoirier]

Our deploy system has an implicit contract: what the Django project can expect.

Documenting that contract would have several benefits:

• Help us keep to the contract as we improve either side (the Django side or the deploy side)
• Make us more aware when we make changes that alter the contract.
• Make it feasible to use other deploy tools to deploy our Django projects if we or others would like to at some point.

Here are some examples of what we might document. These aren't intended to accurately reflect what the template currently does, just to show the kind of things that the contract consists of:

• The Django server will be run using Gunicorn with arguments --a, --b, and --c.
• When started, the environment will contain X, Y, and Z.
• The database(s) will exist and the user/password given in the environment will have full control of it.
• The static files will have been collected and will be served at the URL $STATIC_DIR by some server outside of Django
• Files in the directory $MEDIA_DIR will be served at $MEDIA_URL. The user running the Django server will have write permissions under $MEDIA_DIR.

[dpoirier]

Actually, like all contracts, this one has two sides. The deploy system also has some expectations of the deployed project, such as:

• how to find out what version of Python it expects
• how to find out what needs to be installed in the virtual env

and so forth.

We've tended to just hard-code these in each project's copy of the deploy files that originate in the template, but if we want the deploy system to be replaceable, we need to be more explicit about these.

[mlavin]

For an actionable first step, there are a number of settings which rely on convention rather than explicit configuration. Those related to some of the external additional services (beyond the Django server):

• Nginx: MEDIA_URL, MEDIA_ROOT, STATIC_URL, STATIC_ROOT, Gunicorn port
• DB: name and username
• Broker: username and vhost
• Logging: directory name/layout

I think more of these could be pushed into the process environment though potentially at the cost of readability of the settings.