Minor improvements to 'Deployment with Docker'. Part of #566

docs/deployment-with-docker.rst

@@ -3,47 +3,66 @@ Deployment with Docker
 
 .. index:: Docker, deployment
 
-TODO: Review and revise
+.. warning:: Docker is evolving extremely fast, but it has still some rough edges here and there.
-
+Compose is currently (as of version 1.4)
-**Warning**
-
-Docker is evolving extremely fast, but it has still some rough edges here and there. Compose is currently (as of version 1.4)
 not considered production ready. That means you won't be able to scale to multiple servers and you won't be able to run
 zero downtime deployments out of the box. Consider all this as experimental until you understand all the  implications
 to run docker (with compose) on production.
 
-**Run your app with docker-compose**
-
 Prerequisites:
 
-* docker (at least 1.10)
+* Docker (at least 1.10)
-* docker-compose (at least 1.6)
+* Docker Compose (at least 1.6)
+
+Understand the Compose Setup
+--------------------------------
 
 Before you start, check out the `docker-compose.yml` file in the root of this project. This is where each component
-of this application gets its configuration from. It consists of a `postgres` service that runs the database, `redis`
+of this application gets its configuration from. Notice how it provides configuration for these services:
-for caching, `nginx` as reverse proxy and last but not least the `django` application run by gunicorn.
-{% if cookiecutter.use_celery == 'y' -%}
-Since this application also runs Celery, there are two more services with a service called `celeryworker` that runs the
-celery worker process and `celerybeat` that runs the celery beat process.
-{% endif %}
 
+* `postgres` service that runs the database
+* `redis` for caching
+* `nginx` as reverse proxy
+* `django` is the Django project run by gunicorn
 
-All of these services except `redis` rely on environment variables set by you. There is an `env.example` file in the
+If you chose the `use_celery` option, there are two more services:
+
+* `celeryworker` which runs the celery worker process
+* `celerybeat` which runs the celery beat process
+
+If you chose the `use_letsencrypt` option, you also have:
+
+* `certbot` which keeps your certs from letsencrypt up-to-date
+
+Populate .env With Your Environment Variables
+---------------------------------------------
+
+Some of these services rely on environment variables set by you. There is an `env.example` file in the
 root directory of this project as a starting point. Add your own variables to the file and rename it to `.env`. This
 file won't be tracked by git by default so you'll have to make sure to use some other mechanism to copy your secret if
 you are relying solely on git.
 
+Optional: nginx-proxy Setup
+---------------------------
 
 By default, the application is configured to listen on all interfaces on port 80. If you want to change that, open the
-`docker-compose.yml` file and replace `0.0.0.0` with your own ip. If you are using `nginx-proxy`_ to run multiple
+`docker-compose.yml` file and replace `0.0.0.0` with your own ip.
-application stacks on one host, remove the port setting entirely and add `VIRTUAL_HOST={{cookiecutter.domain_name}}` to your env file.
+
+If you are using `nginx-proxy`_ to run multiple application stacks on one host, remove the port setting entirely and add `VIRTUAL_HOST=example.com` to your env file. Here, replace example.com with the value you entered for `domain_name`.
+
 This pass all incoming requests on `nginx-proxy`_ to the nginx service your application is using.
 
 .. _nginx-proxy: https://github.com/jwilder/nginx-proxy
 
+Optional: Postgres Data Volume Modifications
+---------------------------------------------
+
 Postgres is saving its database files to the `postgres_data` volume by default. Change that if you wan't
 something else and make sure to make backups since this is not done automatically.
 
+Run your app with docker-compose
+--------------------------------
+
 To get started, pull your code from source control (don't forget the `.env` file) and change to your projects root
 directory.
 
@@ -55,7 +74,6 @@ Once this is ready, you can run it with::
 
     docker-compose up
 
-
 To run a migration, open up a second terminal and run::
 
    docker-compose run django python manage.py migrate
@@ -64,7 +82,6 @@ To create a superuser, run::
 
    docker-compose run django python manage.py createsuperuser
 
-
 If you need a shell, run::
 
    docker-compose run django python manage.py shell
@@ -81,7 +98,8 @@ If you want to scale your application, run::
    docker-compose scale celeryworker=2
 
 
-**Don't run the scale command on postgres or celerybeat**
+Don't run the scale command on postgres or celerybeat
+------------------------------------------------------
 
 Once you are ready with your initial setup, you wan't to make sure that your application is run by a process manager to
 survive reboots and auto restarts in case of an error. You can use the process manager you are most familiar with. All