Add troubleshooting section regarding Posgres auth issues - fixes #1678

docs/developing-locally-docker.rst

@@ -6,6 +6,12 @@ Getting Up and Running Locally With Docker
 The steps below will get you up and running with a local development environment.
 All of these commands assume you are in the root of your generated project.
 
+.. note::
+
+    If you're new to Docker, please be aware that some resources are cached system-wide
+    and might reappear if you generate a project multiple times with the same name (e.g.
+    :ref:`this issue with Postgres <docker-posgres-auth-failed>`).
+
 
 Prerequisites
 -------------

docs/troubleshooting.rst

@@ -3,14 +3,48 @@ Troubleshooting
 
 This page contains some advice about errors and problems commonly encountered during the development of Cookiecutter Django applications.
 
+Server Error on sign-up/log-in
+------------------------------
+
+Make sure you have configured the mail backend (e.g. Mailgun) by adding the API key and sender domain
+
+.. include:: mailgun.rst
+
+.. _docker-posgres-auth-failed:
+
+Docker: Postgres authentication failed
+--------------------------------------
+
+Examples of logs::
+
+    postgres_1      | 2018-06-07 19:11:23.963 UTC [81] FATAL:  password authentication failed for user "pydanny"
+    postgres_1      | 2018-06-07 19:11:23.963 UTC [81] DETAIL:  Password does not match for user "pydanny".
+    postgres_1      | 	Connection matched pg_hba.conf line 95: "host all all all md5"
+
+If you recreate the project multiple times with the same name, Docker would preserve the volumes for the postgres container between projects. Here is what happens:
+
+#. You generate the project the first time. The .env postgres file is populated with the random password
+#. You run the docker-compose and the containers are created. The postgres container creates the database based on the .env file credentials
+#. You "regenerate" the project with the same name, so the postgres .env file is populated with a new random password
+#. You run docker-compose. Since the names of the containers are the same, docker will try to start them (not create them from scratch i.e. it won't execute the Dockerfile to recreate the database). When this happens, it tries to start the database based on the new credentials which do not match the ones that the database was created with, and you get the error message above.
+
+To fix this, you can either:
+
+- Clear your project-related Docker cache with ``docker-compose -f local.yml down --volumes --rmi all``.
+- Use the Docker volume sub-commands to find volumes (`ls`_) and remove them (`rm`_).
+- Use the `prune`_ command to clear system-wide (use with care!).
+
+.. _ls: https://docs.docker.com/engine/reference/commandline/volume_ls/
+.. _rm: https://docs.docker.com/engine/reference/commandline/volume_rm/
+.. _prune: https://docs.docker.com/v17.09/engine/reference/commandline/system_prune/
+
+Others
+------
+
 #. ``project_slug`` must be a valid Python module name or you will have issues on imports.
 
 #. ``jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'now'.``: please upgrade your cookiecutter version to >= 1.4 (see `#528`_)
 
-#. Internal server error on user registration: make sure you have configured the mail backend (e.g. Mailgun) by adding the API key and sender domain
-
-   .. include:: mailgun.rst
-
 #. New apps not getting created in project root: This is the expected behavior, because cookiecutter-django does not change the way that django startapp works, you'll have to fix this manually (see `#1725`_)
 
 .. _#528: https://github.com/pydanny/cookiecutter-django/issues/528#issuecomment-212650373