Merge pull request #1805 from pydanny/docs-local-dev

Update documentation for local developement on bare metal

docs/developing-locally.rst

@@ -9,24 +9,55 @@ Setting Up Development Environment
 
 Make sure to have the following on your host:
 
-* virtualenv_;
+* Python 3.6
-* pip;
+* PostgreSQL_.
-* PostgreSQL.
+* Redis_, if using Celery
 
 First things first.
 
-#. `Create a virtualenv`_.
+#. Create a virtualenv: ::
 
-#. Activate the virtualenv you have just created.
+    $ python3.6 -m venv <virtual env path>
+
+#. Activate the virtualenv you have just created: ::
+
+    $ source <virtual env path>/bin/activate
 
 #. Install development requirements: ::
 
     $ pip install -r requirements/local.txt
 
-#. 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): ::
+#. Create a new PostgreSQL database using createdb_: ::
 
     $ createdb <what you've entered as the project_slug at setup stage>
 
+   .. note::
+
+       if this is the first time a database is created on your machine you might need an
+       `initial PostgreSQL set up`_ to allow local connections & set a password for
+       the ``postgres`` user. The `postgres documentation`_ explains the syntax of the config file
+       that you need to change.
+
+
+#. Set the environment variables for your database(s): ::
+
+    $ export DATABASE_URL=postgres://postgres:<password>@127.0.0.1:5432/<DB name given to createdb>
+    # Optional: set broker URL if using Celery
+    $ export CELERY_BROKER_URL=redis://localhost:6379/0
+
+   .. note::
+
+       Check out the :ref:`settings` page for a comprehensive list of the environments variables.
+
+   .. seealso::
+
+       To help setting up your environment variables, you have a few options:
+
+       * create an ``.env`` file in the root of your project and define all the variables you need in it.
+         Then you just need to have ``DJANGO_READ_DOT_ENV_FILE=True`` in your machine and all the variables
+         will be read.
+       * Use a local environment manager like `direnv`_
+
 #. Apply migrations: ::
 
     $ python manage.py migrate
@@ -35,8 +66,12 @@ First things first.
 
     $ python manage.py runserver 0.0.0.0:8000
 
-.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
+.. _PostgreSQL: https://www.postgresql.org/download/
-.. _`Create a virtualenv`: https://virtualenv.pypa.io/en/stable/userguide/
+.. _Redis: https://redis.io/download
+.. _createdb: https://www.postgresql.org/docs/current/static/app-createdb.html
+.. _initial PostgreSQL set up: http://suite.opengeo.org/docs/latest/dataadmin/pgGettingStarted/firstconnect.html
+.. _postgres documentation: https://www.postgresql.org/docs/current/static/auth-pg-hba-conf.html
+.. _direnv: https://direnv.net/
 
 
 Setup Email Backend
@@ -69,9 +104,7 @@ For instance, one of the packages we depend upon, ``django-allauth`` sends verif
 
 Now you have your own mail server running locally, ready to receive whatever you send it.
 
-.. _`Download the latest MailHog release`: https://github.com/mailhog/MailHog/releases
+.. _`Download the latest MailHog release`: https://github.com/mailhog/MailHog
-.. _`properly configured`: https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend
-
 
 Console
 ~~~~~~~
@@ -88,11 +121,8 @@ In production, we have Mailgun_ configured to have your back!
 Sass Compilation & Live Reloading
 ---------------------------------
 
-If you’d like to take advantage of live reloading and Sass compilation you can do so with a little bit of preparation_.
+If you’d like to take advantage of live reloading and Sass compilation you can do so with a little
-
+bit of preparation, see :ref:`sass-compilation-live-reload`.
-
-.. _preparation: https://cookiecutter-django.readthedocs.io/en/latest/live-reloading-and-sass-compilation.html
-
 
 Summary
 -------

docs/index.rst

@@ -17,7 +17,6 @@ Contents:
    developing-locally-docker
    settings
    linters
-   live-reloading-and-sass-compilation
    deployment-on-pythonanywhere
    deployment-on-heroku
    deployment-with-docker

docs/installing_postgres.rst

@@ -1,17 +0,0 @@
-PostgreSQL Installation Basics
-==============================
-
-.. index:: pip, virtualenv, PostgreSQL
-
-The steps below will get you up and running with PostgreSQL. This assumes you have pip and virtualenv_ installed. 
-
-.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
-
-On Mac
-
-Install PostgreSQLapp_ from the browser and move PostGresSQL into your applications folder. Then install PostgreSQL from HomeBrew_.
-
-	$ brew install postgres
-
-.. _PostgreSQLapp: http://postgresapp.com/
-.. _HomeBrew: http://brew.sh/

docs/linters.rst

@@ -5,9 +5,9 @@ Linters
 
 
 flake8
--------
+------
 
-To run flake8:
+To run flake8: ::
 
     $ flake8
 
@@ -19,7 +19,7 @@ The config for flake8 is located in setup.cfg. It specifies:
 pylint
 ------
 
-This is included in flake8's checks, but you can also run it separately to see a more detailed report:
+This is included in flake8's checks, but you can also run it separately to see a more detailed report: ::
 
     $ pylint <python files that you wish to lint>
 
@@ -31,9 +31,9 @@ The config for pylint is located in .pylintrc. It specifies:
 * max-parents=13
 
 pycodestyle
------
+-----------
 
-This is included in flake8's checks, but you can also run it separately to see a more detailed report:
+This is included in flake8's checks, but you can also run it separately to see a more detailed report: ::
 
     $ pycodestyle <python files that you wish to lint>
 

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

@@ -1,3 +1,5 @@
+.. _sass-compilation-live-reload:
+
 Sass Compilation & Live Reloading
 =================================
 

docs/settings.rst

@@ -1,7 +1,7 @@
 .. _settings:
 
 Settings
-==========
+========
 
 This project relies extensively on environment settings which **will not work with Apache/mod_wsgi setups**. It has been deployed successfully with both Gunicorn/Nginx and even uWSGI/Nginx.
 
@@ -18,11 +18,10 @@ DJANGO_READ_DOT_ENV_FILE                READ_DOT_ENV_FILE           False
 ======================================= =========================== ============================================== ======================================================================
 Environment Variable                    Django Setting              Development Default                            Production Default
 ======================================= =========================== ============================================== ======================================================================
+DATABASE_URL                            DATABASES                   auto w/ Docker; postgres://project_slug w/o    raises error
 DJANGO_ADMIN_URL                        n/a                         'admin/'                                       raises error
-DJANGO_CACHES                           CACHES (default)            locmem                                         redis
-DJANGO_DATABASES                        DATABASES (default)         See code                                       See code
 DJANGO_DEBUG                            DEBUG                       True                                           False
-DJANGO_SECRET_KEY                       SECRET_KEY                  !!!SET DJANGO_SECRET_KEY!!!                    raises error
+DJANGO_SECRET_KEY                       SECRET_KEY                  auto-generated                                 raises error
 DJANGO_SECURE_BROWSER_XSS_FILTER        SECURE_BROWSER_XSS_FILTER   n/a                                            True
 DJANGO_SECURE_SSL_REDIRECT              SECURE_SSL_REDIRECT         n/a                                            True
 DJANGO_SECURE_CONTENT_TYPE_NOSNIFF      SECURE_CONTENT_TYPE_NOSNIFF n/a                                            True
@@ -41,6 +40,7 @@ The following table lists settings and their defaults for third-party applicatio
 ======================================= =========================== ============================================== ======================================================================
 Environment Variable                    Django Setting              Development Default                            Production Default
 ======================================= =========================== ============================================== ======================================================================
+CELERY_BROKER_URL                       CELERY_BROKER_URL           auto w/ Docker; raises error w/o               raises error
 DJANGO_AWS_ACCESS_KEY_ID                AWS_ACCESS_KEY_ID           n/a                                            raises error
 DJANGO_AWS_SECRET_ACCESS_KEY            AWS_SECRET_ACCESS_KEY       n/a                                            raises error
 DJANGO_AWS_STORAGE_BUCKET_NAME          AWS_STORAGE_BUCKET_NAME     n/a                                            raises error
@@ -49,8 +49,6 @@ DJANGO_SENTRY_CLIENT                    SENTRY_CLIENT               n/a
 DJANGO_SENTRY_LOG_LEVEL                 SENTRY_LOG_LEVEL            n/a                                            logging.INFO
 MAILGUN_API_KEY                         MAILGUN_ACCESS_KEY          n/a                                            raises error
 MAILGUN_DOMAIN                          MAILGUN_SENDER_DOMAIN       n/a                                            raises error
-NEW_RELIC_APP_NAME                      NEW_RELIC_APP_NAME          n/a                                            raises error
-NEW_RELIC_LICENSE_KEY                   NEW_RELIC_LICENSE_KEY       n/a                                            raises error
 ======================================= =========================== ============================================== ======================================================================
 
 --------------------------

{{cookiecutter.project_slug}}/.gitignore

@@ -333,6 +333,7 @@ tags
 [Ss]cripts
 pyvenv.cfg
 pip-selfcheck.json
+.env
 {% endif %}
 
 ### Project template