Update the docs

docs/deployment-with-docker.rst

@@ -1,72 +1,66 @@
 Deployment with Docker
 ======================
 
-.. index:: Docker, deployment
+.. index:: deployment, docker, docker-compose, compose
+
 
 Prerequisites
 -------------
 
-* Docker (at least 1.10)
-* Docker Compose (at least 1.6)
+* Docker 1.10+.
+* Docker Compose 1.6+
 
-Understand the Compose Setup
-----------------------------
 
-Before you start, check out the `production.yml` file in the root of this project. This is where each component
-of this application gets its configuration from. Notice how it provides configuration for these services:
+Understanding the Docker Compose Setup
+--------------------------------------
 
-* `postgres` service that runs the database
-* `redis` for caching
-* `caddy` as webserver
-* `django` is the Django project run by gunicorn
+Before you begin, check out the ``production.yml`` file in the root of this project. Keep note of how it provides configuration for the following services:
 
-If you chose the `use_celery` option, there are two more services:
+* ``django``: your application running behind ``Gunicorn``;
+* ``postgres``: PostgreSQL database with the application's relational data;
+* ``redis``: Redis instance for caching;
+* ``caddy``: Caddy web server with HTTPS on by default.
 
-* `celeryworker` which runs the celery worker process
-* `celerybeat` which runs the celery beat process
+Provided you have opted for Celery (via setting ``use_celery`` to ``y``) there are two more services:
+
+* ``celeryworker`` running a Celery worker process;
+* ``celerybeat`` running a Celery beat process.
 
-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.
+Configuring the Stack
+---------------------
 
-It is **highly recommended** that before you build your production application, you set your POSTGRES_USER value here. This will create a non-default user for the postgres image. If you do not set this user before building the application, the default user 'postgres' will be created, and this user will not be able to create or restore backups.
+The majority of services above are configured through the use of environment variables. Just check out :ref:`envs` and you will know the drill.
 
-To obtain logs and information about crashes in a production setup, make sure that you have access to an external Sentry instance (e.g. by creating an account with `sentry.io`_), and set the `DJANGO_SENTRY_DSN` variable. This should be enough to report crashes to Sentry.
+To obtain logs and information about crashes in a production setup, make sure that you have access to an external Sentry instance (e.g. by creating an account with `sentry.io`_), and set the ``DJANGO_SENTRY_DSN`` variable.
 
 You will probably also need to setup the Mail backend, for example by adding a `Mailgun`_ API key and a `Mailgun`_ sender domain, otherwise, the account creation view will crash and result in a 500 error when the backend attempts to send an email to the account owner.
 
 .. _sentry.io: https://sentry.io/welcome
 .. _Mailgun: https://mailgun.com
 
+
 Optional: Use AWS IAM Role for EC2 instance
-------------------------------------
-If you are deploying to AWS, you can use the IAM role to substitute AWS credentials, after which it's safe to remove the `AWS_ACCESS_KEY_ID` AND `AWS_SECRET_ACCESS_KEY` from the `.env`. To do it, create an `IAM role`_ and `attach`_ it to the existing EC2 instance or create a new EC2 instance with that role. The role should assume a minimum permission of `AmazonS3FullAccess`.
+-------------------------------------------
+
+If you are deploying to AWS, you can use the IAM role to substitute AWS credentials, after which it's safe to remove the ``AWS_ACCESS_KEY_ID`` AND ``AWS_SECRET_ACCESS_KEY`` from ``.envs/.production/.django``. To do it, create an `IAM role`_ and `attach`_ it to the existing EC2 instance or create a new EC2 instance with that role. The role should assume, at minimum, the ``AmazonS3FullAccess`` permission.
 
 .. _IAM role: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
 .. _attach: https://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/
 
-HTTPS is on by default
+
+HTTPS is On by Default
 ----------------------
 
 SSL (Secure Sockets Layer) is a standard security technology for establishing an encrypted link between a server and a client, typically in this case, a web server (website) and a browser. Not having HTTPS means that malicious network users can sniff authentication credentials between your website and end users' browser.
 
 It is always better to deploy a site behind HTTPS and will become crucial as the web services extend to the IoT (Internet of Things). For this reason, we have set up a number of security defaults to help make your website secure:
 
-* In the `.env.example`, we have made it simpler for you to change the default `Django Admin` into a custom name through an environmental variable. This should make it harder to guess the access to the admin panel.
-
-* If you are not using a subdomain of the domain name set in the project, then remember to put the your staging/production IP address in the :code:`DJANGO_ALLOWED_HOSTS` environment variable (see :ref:`settings`) before you deploy your website. Failure to do this will mean you will not have access to your website through the HTTP protocol.
+* If you are not using a subdomain of the domain name set in the project, then remember to put the your staging/production IP address in the ``DJANGO_ALLOWED_HOSTS`` environment variable (see :ref:`settings`) before you deploy your website. Failure to do this will mean you will not have access to your website through the HTTP protocol.
 
 * Access to the Django admin is set up by default to require HTTPS in production or once *live*.
 
-
-HTTPS is configured by default
-------------------------------
-
-The Caddy webserver used in the default configuration will get you a valid certificate from Lets Encrypt and update it automatically. All you need to do to enable this is to make sure that your DNS records are pointing to the server Caddy runs on.
+The Caddy web server used in the default configuration will get you a valid certificate from Lets Encrypt and update it automatically. All you need to do to enable this is to make sure that your DNS records are pointing to the server Caddy runs on.
 
 You can read more about this here at `Automatic HTTPS`_ in the Caddy docs.
 
@@ -76,15 +70,13 @@ You can read more about this here at `Automatic HTTPS`_ in the Caddy docs.
 (Optional) Postgres Data Volume Modifications
 ---------------------------------------------
 
-Postgres is saving its database files to the `postgres_data` volume by default. Change that if you want something else and make sure to make backups since this is not done automatically.
+Postgres is saving its database files to the ``postgres_data`` volume by default. Change that if you want 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.
+Building & Running Production Stack
+-----------------------------------
 
-You'll need to build the stack first. To do that, run::
+You will need to build the stack first. To do that, run::
 
     docker-compose -f production.yml build
 
@@ -104,9 +96,7 @@ If you need a shell, run::
 
    docker-compose -f production.yml run --rm django python manage.py shell
 
-To get an output of all running containers.
-
-To check your logs, run::
+To check the logs out, run::
 
    docker-compose -f production.yml logs
 
@@ -115,21 +105,21 @@ If you want to scale your application, run::
    docker-compose -f production.yml scale django=4
    docker-compose -f production.yml scale celeryworker=2
 
-.. warning:: Don't run the scale command on postgres, celerybeat, or caddy.
+.. warning:: don't try to scale ``postgres``, ``celerybeat``, or ``caddy``.
 
-If you have errors, you can always check your stack with `docker-compose`. Switch to your projects root directory and run::
+To see how your containers are doing run::
 
     docker-compose -f production.yml ps
 
 
-Supervisor Example
+Example: Supervisor
 -------------------
 
 Once you are ready with your initial setup, you want 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
-it needs to do is to run `docker-compose -f production.yml up` in your projects root directory.
+it needs to do is to run ``docker-compose -f production.yml up`` in your projects root directory.
 
-If you are using `supervisor`, you can use this file as a starting point::
+If you are using ``supervisor``, you can use this file as a starting point::
 
     [program:{{cookiecutter.project_slug}}]
     command=docker-compose -f production.yml up
@@ -139,11 +129,11 @@ If you are using `supervisor`, you can use this file as a starting point::
     autorestart=true
     priority=10
 
-Place it in `/etc/supervisor/conf.d/{{cookiecutter.project_slug}}.conf` and run::
+Move it to ``/etc/supervisor/conf.d/{{cookiecutter.project_slug}}.conf`` and run::
 
     supervisorctl reread
     supervisorctl start {{cookiecutter.project_slug}}
 
-To get the status, run::
+For status check, run::
 
     supervisorctl status

docs/developing-locally-docker.rst

@@ -77,6 +77,8 @@ Here, ``django`` is the target service we are executing the commands against.
 When ``DEBUG`` is set to ``True``, the host is validated against ``['localhost', '127.0.0.1', '[::1]']``. This is adequate when running a ``virtualenv``. For Docker, in the ``config.settings.local``, add your host development server IP to ``INTERNAL_IPS`` or ``ALLOWED_HOSTS`` if the variable exists.
 
 
+.. _envs:
+
 Configuring the Environment
 ---------------------------
 

docs/developing-locally.rst

@@ -3,74 +3,98 @@ Getting Up and Running Locally
 
 .. index:: pip, virtualenv, PostgreSQL
 
-The steps below will get you up and running with a local development environment. We assume you have the following installed:
 
-* pip
-* virtualenv
-* PostgreSQL
+Setting Up Development Environment
+----------------------------------
 
-First make sure to create and activate a virtualenv_.
+Make sure to have the following on your host:
 
-.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
+* virtualenv_;
+* pip;
+* PostgreSQL.
+
+First things first.
+
+#. `Create a virtualenv`_.
+
+#. Activate the virtualenv you have just created.
 
-Then install the requirements for your local development::
+#. Install development requirements: ::
 
     $ pip install -r requirements/local.txt
 
-Then, create a PostgreSQL database with the following command, where `[project_slug]` is what value you entered for your project's `project_slug`::
+#. Create a new PostgreSQL database (note: if this is the first time a database is created on your machine you might need to alter a localhost-related entry in your ``pg_hba.conf`` so as to utilize ``trust`` policy): ::
 
-    $ createdb [project_slug]
+    $ createdb <what you've entered as the project_slug at setup stage>
 
-You can now run the usual Django ``migrate`` and ``runserver`` commands::
+#. Apply migrations: ::
 
     $ python manage.py migrate
-    $ python manage.py runserver
 
-At this point you can take a break from setup and start getting to know the files in the project.
+#. See the application being served through Django development server: ::
+
+    $ python manage.py runserver 0.0.0.0:8000
+
+.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
+.. _`Create a virtualenv`: https://virtualenv.pypa.io/en/stable/userguide/
+
 
-But if you want to go further with setup, read on.
+Setup Email Backend
+-------------------
 
-(Note: the following sections still need to be revised)
+MailHog
+~~~~~~~
 
-Setting Up Env Vars for Production
------------------------------------
+.. note:: In order for the project to support MailHog_ it must have been bootstrapped with ``use_mailhog`` set to ``y``.
 
-`Cookiecutter Django` uses the excellent `django-environ`_ package, which includes a ``DATABASE_URL`` environment variable to simplify database configuration in your Django settings.
+MailHog is used to receive emails during development, it is written in Go and has no external dependencies.
 
-Rename env.example to .env to begin updating the file with your own environment variables. To add your database, define ``DATABASE_URL`` and add it to the .env file, as shown below:
+For instance, one of the packages we depend upon, ``django-allauth`` sends verification emails to new users signing up as well as to the existing ones who have not yet verified themselves.
 
-.. parsed-literal::
+#. `Download the latest MailHog release`_ for your OS.
 
-    DATABASE_URL="postgres://*<pg_user_name>*:*<pg_user_password>*\ @127.0.0.1:\ *<pg_port>*/*<pg_database_name>*"
+#. Rename the build to ``MailHog``.
 
-.. _django-environ: http://django-environ.readthedocs.io
+#. Copy the file to the project root.
 
-Setup your email backend
--------------------------
+#. Make it executable: ::
 
-django-allauth sends an email to verify users (and superusers) after signup and login (if they are still not verified). To send email you need to `configure your email backend`_
+    $ chmod +x MailHog
 
-.. _configure your email backend: https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend
+#. Spin up another terminal window and start it there: ::
 
-In development you can (optionally) use MailHog_ for email testing. MailHog is built with Go so there are no dependencies. To use MailHog:
+    ./MailHog
 
-1. `Download the latest release`_ for your operating system
-2. Rename the executable to ``mailhog`` and copy it to the root of your project directory
-3. Make sure it is executable (e.g. ``chmod +x mailhog``)
-4. Execute mailhog from the root of your project in a new terminal window (e.g. ``./mailhog``)
-5. All emails generated from your django app can be seen on http://127.0.0.1:8025/
+#. Check out `<http://127.0.0.1:8025/>`_ to see how it goes.
 
-.. _Mailhog: https://github.com/mailhog/MailHog/
-.. _Download the latest release: https://github.com/mailhog/MailHog/releases
+Now you have your own mail server running locally, ready to receive whatever you send it.
 
-Alternatively simply output emails to the console via: ``EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'``
+.. _MailHog: https://github.com/mailhog/MailHog/
+.. _`properly configured`: https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend
 
-In production basic email configuration is setup to send emails with Mailgun_
+
+Console
+~~~~~~~
+
+.. note:: If you have generated your project with ``use_mailhog`` set to ``n`` this will be a default setup.
+
+Alternatively, deliver emails over console via ``EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'``.
+
+In production, we have Mailgun_ configured to have your back!
 
 .. _Mailgun: https://www.mailgun.com/
 
-**Live reloading and Sass CSS compilation**
 
-If you’d like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with a little bit of `prep work`_.
+Sass Compilation & Live Reloading
+---------------------------------
+
+If you’d like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with a little bit of preparation_.
+
+.. _`Download the latest MailHog release`: https://github.com/mailhog/MailHog/releases
+.. _preparation: https://cookiecutter-django.readthedocs.io/en/latest/live-reloading-and-sass-compilation.html
+
+
+Summary
+-------
 
-.. _prep work: https://cookiecutter-django.readthedocs.io/en/latest/live-reloading-and-sass-compilation.html
+Congratulations, you have made it! Keep on reading to unleash full potential of Cookiecutter Django.

docs/live-reloading-and-sass-compilation.rst

@@ -1,5 +1,5 @@
-Live reloading and Sass CSS compilation
-=======================================
+Sass Compilation & Live Reloading
+=================================
 
 If you'd like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with a little bit of prep work.