From 6dd64ddd5316d2ecd610fc95fc3714b2b1245a5d Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sat, 15 Sep 2018 21:23:06 +0100 Subject: [PATCH 1/7] Update documentation for bare metal local development - Mention the need for Redis if Celery is selected - Link to PostgreSQL & Redis download pages - Detail better how to set the environment - Improve internal links using Sphinx' :ref - Remove unused link --- docs/developing-locally.rst | 59 ++++++++++++++------ docs/live-reloading-and-sass-compilation.rst | 2 + {{cookiecutter.project_slug}}/.gitignore | 1 + 3 files changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/developing-locally.rst b/docs/developing-locally.rst index 59079453..8a584165 100644 --- a/docs/developing-locally.rst +++ b/docs/developing-locally.rst @@ -9,24 +9,53 @@ Setting Up Development Environment Make sure to have the following on your host: -* virtualenv_; -* pip; -* PostgreSQL. +* Python 3.6 +* PostgreSQL_. +* Redis_, if using Celery First things first. -#. `Create a virtualenv`_. +#. Create a virtualenv: :: -#. Activate the virtualenv you have just created. + $ python3 -m venv + +#. Activate the virtualenv you have just created: :: + + $ source /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 + .. 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, see the + `postgres documentation`_ for more details. + +#. Set the environment variables for your database(s): :: + + $ export DATABASE_URL=postgres:// + # 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 +64,11 @@ First things first. $ 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/ +.. _PostgreSQL: https://www.postgresql.org/download/ +.. _Redis: https://redis.io/download +.. _createdb: https://www.postgresql.org/docs/current/static/app-createdb.html +.. _postgres documentation: https://www.postgresql.org/docs/current/static/auth-pg-hba-conf.html +.. _direnv: https://direnv.net/ Setup Email Backend @@ -69,9 +101,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 -.. _`properly configured`: https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend - +.. _`Download the latest MailHog release`: https://github.com/mailhog/MailHog Console ~~~~~~~ @@ -88,11 +118,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_. - - -.. _preparation: https://cookiecutter-django.readthedocs.io/en/latest/live-reloading-and-sass-compilation.html - +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`. Summary ------- diff --git a/docs/live-reloading-and-sass-compilation.rst b/docs/live-reloading-and-sass-compilation.rst index db8d681f..a55b4fd8 100644 --- a/docs/live-reloading-and-sass-compilation.rst +++ b/docs/live-reloading-and-sass-compilation.rst @@ -1,3 +1,5 @@ +.. _sass-compilation-live-reload: + Sass Compilation & Live Reloading ================================= diff --git a/{{cookiecutter.project_slug}}/.gitignore b/{{cookiecutter.project_slug}}/.gitignore index 679fb902..1eefea0f 100644 --- a/{{cookiecutter.project_slug}}/.gitignore +++ b/{{cookiecutter.project_slug}}/.gitignore @@ -333,6 +333,7 @@ tags [Ss]cripts pyvenv.cfg pip-selfcheck.json +.env {% endif %} ### Project template From 49e12332e807d00507e409d43610134edb14d5fd Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sat, 15 Sep 2018 21:23:29 +0100 Subject: [PATCH 2/7] Add a _static folder to silence Sphinx' warning --- docs/_static/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/_static/.gitkeep diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b From 993de2d4091bc6ded88c4add15ddabf26dfc1f6a Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sat, 15 Sep 2018 21:24:22 +0100 Subject: [PATCH 3/7] Remove unused details for installing PostgreSQL, link to the official website --- docs/index.rst | 1 - docs/installing_postgres.rst | 17 ----------------- 2 files changed, 18 deletions(-) delete mode 100644 docs/installing_postgres.rst diff --git a/docs/index.rst b/docs/index.rst index c9f70ab1..856b931f 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/installing_postgres.rst b/docs/installing_postgres.rst deleted file mode 100644 index 3b37e819..00000000 --- a/docs/installing_postgres.rst +++ /dev/null @@ -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/ \ No newline at end of file From c51fd710d264bba37afe99ff38ca5cd1355dd5aa Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sat, 15 Sep 2018 21:25:40 +0100 Subject: [PATCH 4/7] Update settings page - Add a few missing settings - Remove outdated ones - Detail behaviour with URL for databases --- docs/settings.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index 6e71a515..26b161a0 100644 --- a/docs/settings.rst +++ b/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 ======================================= =========================== ============================================== ====================================================================== -------------------------- From fa162dc970f8743088fc92d4bfb1fe31902c0056 Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sat, 15 Sep 2018 21:26:13 +0100 Subject: [PATCH 5/7] Update linters page for better syntax highlighting --- docs/linters.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/linters.rst b/docs/linters.rst index feb59d03..e59ff0df 100644 --- a/docs/linters.rst +++ b/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 @@ -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 From 46ab5aefc764770d4e0e0ddfcea4d6767b5501c4 Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sun, 16 Sep 2018 20:04:50 +0100 Subject: [PATCH 6/7] Use a more specific version of python for venv --- docs/developing-locally.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developing-locally.rst b/docs/developing-locally.rst index 8a584165..719df022 100644 --- a/docs/developing-locally.rst +++ b/docs/developing-locally.rst @@ -17,7 +17,7 @@ First things first. #. Create a virtualenv: :: - $ python3 -m venv + $ python3.6 -m venv #. Activate the virtualenv you have just created: :: From 0de682f22d76978d8af7b4ee80e721d9e1941b21 Mon Sep 17 00:00:00 2001 From: Bruno Alla Date: Sat, 29 Sep 2018 12:24:28 +0100 Subject: [PATCH 7/7] Update database setup instructions for developing locally --- docs/developing-locally.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/developing-locally.rst b/docs/developing-locally.rst index 719df022..7d5591ac 100644 --- a/docs/developing-locally.rst +++ b/docs/developing-locally.rst @@ -33,13 +33,15 @@ First things first. .. 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, see the - `postgres documentation`_ for more details. + 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:// + $ export DATABASE_URL=postgres://postgres:@127.0.0.1:5432/ # Optional: set broker URL if using Celery $ export CELERY_BROKER_URL=redis://localhost:6379/0 @@ -67,6 +69,7 @@ First things first. .. _PostgreSQL: https://www.postgresql.org/download/ .. _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/