diff --git a/{{cookiecutter.repo_name}}/CONTRIBUTING.rst b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst index 56392e690..605e06a0e 100644 --- a/{{cookiecutter.repo_name}}/CONTRIBUTING.rst +++ b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst @@ -62,11 +62,7 @@ Ready to contribute? Here's how to set up `{{ cookiecutter.repo_name }}` for loc $ git clone https://github.com/your_username_here/{{ cookiecutter.repo_name }}.git -3. Install your local copy into a `virtualenv `_. Assuming you have `virtualenvwrapper `_ installed, this is how you set up your fork for local development:: - - $ mkvirtualenv {{ cookiecutter.repo_name }} - $ cd {{ cookiecutter.repo_name }}/ - $ python setup.py develop +3. Install your local copy following the instructions in the docs https://{{ cookiecutter.repo_name }}.readthedocs.org/en/latest/install.html 4. Create a branch for local development:: @@ -74,21 +70,14 @@ Ready to contribute? Here's how to set up `{{ cookiecutter.repo_name }}` for loc Now you can make your changes locally. -5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:: - $ flake8 {{ cookiecutter.repo_name }} tests - $ python setup.py test - $ tox - - To get flake8 and tox, just pip install them into your virtualenv. - -6. Commit your changes and push your branch to GitHub:: +5. Commit your changes and push your branch to GitHub:: $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature -7. Submit a pull request through the GitHub website. +6. Submit a pull request through the GitHub website. Pull Request Guidelines ----------------------- @@ -97,15 +86,4 @@ Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put - your new functionality into a function with a docstring, and add the - feature to the list in README.rst. -3. The pull request should work for Python 2.6, 2.7, 3.3, and 3.4, and for PyPy. Check - https://travis-ci.org/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}/pull_requests - and make sure that the tests pass for all supported Python versions. - -Tips ----- - -To run a subset of tests:: - - $ python -m unittest tests.test_{{ cookiecutter.repo_name }} + your new functionality into a function with a docstring. diff --git a/{{cookiecutter.repo_name}}/README.rst b/{{cookiecutter.repo_name}}/README.rst index e10c9b752..8b843082c 100644 --- a/{{cookiecutter.repo_name}}/README.rst +++ b/{{cookiecutter.repo_name}}/README.rst @@ -11,142 +11,15 @@ Settings {{cookiecutter.project_name}} 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. -For configuration purposes, the following table maps the '{{cookiecutter.project_name}}' environment variables to their Django setting: - -======================================= =========================== ============================================== =========================================== -Environment Variable Django Setting Development Default Production Default -======================================= =========================== ============================================== =========================================== -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 -DJANGO_CACHES CACHES locmem memcached -DJANGO_DATABASES DATABASES See code See code -DJANGO_DEBUG DEBUG True False -DJANGO_EMAIL_BACKEND EMAIL_BACKEND django.core.mail.backends.console.EmailBackend django.core.mail.backends.smtp.EmailBackend -DJANGO_SECRET_KEY SECRET_KEY CHANGEME!!! 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 -DJANGO_SECURE_FRAME_DENY SECURE_FRAME_DENY n/a True -DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS HSTS_INCLUDE_SUBDOMAINS n/a True -DJANGO_SESSION_COOKIE_HTTPONLY SESSION_COOKIE_HTTPONLY n/a True -DJANGO_SESSION_COOKIE_SECURE SESSION_COOKIE_SECURE n/a False -======================================= =========================== ============================================== =========================================== - -* TODO: Add vendor-added settings in another table +For configuration purposes, see the table maps the '{{cookiecutter.project_name}}' environment variables to their Django setting: https://{{ cookiecutter.repo_name }}.readthedocs.org/en/latest/install.html#Settings Getting up and running ---------------------- -The steps below will get you up and running with a local development environment. We assume you have the following installed: - -* pip -* virtualenv -* PostgreSQL - -First make sure to create and activate a virtualenv_, then open a terminal at the project root and install the requirements for local development:: - - $ pip install -r requirements/local.txt - -.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/ - -You can now run the usual Django ``runserver`` command (replace ``yourapp`` with the name of the directory containing the Django project):: - - $ python yourapp/manage.py runserver - -The base app will run but you'll need to carry out a few steps to make the sign-up and login forms work. These are currently detailed in `issue #39`_. - -.. _issue #39: https://github.com/pydanny/cookiecutter-django/issues/39 - -**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 the included Grunt task. - -Make sure that nodejs_ is installed. Then in the project root run:: - - $ npm install grunt - -.. _nodejs: http://nodejs.org/download/ - -Now you just need:: - - $ grunt serve - -The base app will now run as it would with the usual ``manage.py runserver`` but with live reloading and Sass compilation enabled. - -To get live reloading to work you'll probably need to install an `appropriate browser extension`_ - -.. _appropriate browser extension: http://feedback.livereload.com/knowledgebase/articles/86242-how-do-i-install-and-use-the-browser-extensions- - -It's time to write the code!!! +Just follow the steps described in https://{{ cookiecutter.repo_name }}.readthedocs.org/en/latest/install.html and you'll get yourself an up and running local development environment. Deployment ------------ -It is possible to deploy to Heroku or to your own server by using Dokku, an open source Heroku clone. - -Heroku -^^^^^^ - -Run these commands to deploy the project to Heroku: - -.. code-block:: bash - - heroku create --buildpack https://github.com/heroku/heroku-buildpack-python - heroku addons:add heroku-postgresql:dev - heroku addons:add pgbackups:auto-month - heroku addons:add sendgrid:starter - heroku addons:add memcachier:dev - heroku pg:promote DATABASE_URL - heroku config:set DJANGO_CONFIGURATION=Production - heroku config:set DJANGO_SECRET_KEY=RANDOM_SECRET_KEY_HERE - heroku config:set DJANGO_AWS_ACCESS_KEY_ID=YOUR_AWS_ID_HERE - heroku config:set DJANGO_AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY_HERE - heroku config:set DJANGO_AWS_STORAGE_BUCKET_NAME=YOUR_AWS_S3_BUCKET_NAME_HERE - git push heroku master - heroku run python {{cookiecutter.repo_name}}/manage.py migrate - heroku run python {{cookiecutter.repo_name}}/manage.py createsuperuser - heroku open - -Dokku -^^^^^ - -You need to make sure you have a server running Dokku with at least 1GB of RAM. Backing services are -added just like in Heroku however you must ensure you have the relevant Dokku plugins installed. - -.. code-block:: bash - - cd /var/lib/dokku/plugins - git clone https://github.com/rlaneve/dokku-link.git link - git clone https://github.com/jezdez/dokku-memcached-plugin memcached - git clone https://github.com/jezdez/dokku-postgres-plugin postgres - dokku plugins-install - -You can specify the buildpack you wish to use by creating a file name .env containing the following. - -.. code-block:: bash - - export BUILDPACK_URL= - -You can then deploy by running the following commands. - -.. code-block:: bash - - git remote add dokku dokku@yourservername.com:{{cookiecutter.repo_name}} - git push dokku master - ssh -t dokku@yourservername.com dokku memcached:create {{cookiecutter.repo_name}}-memcached - ssh -t dokku@yourservername.com dokku memcached:link {{cookiecutter.repo_name}}-memcached {{cookiecutter.repo_name}} - ssh -t dokku@yourservername.com dokku postgres:create {{cookiecutter.repo_name}}-postgres - ssh -t dokku@yourservername.com dokku postgres:link {{cookiecutter.repo_name}}-postgres {{cookiecutter.repo_name}} - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_CONFIGURATION=Production - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_SECRET_KEY=RANDOM_SECRET_KEY_HERE - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_AWS_ACCESS_KEY_ID=YOUR_AWS_ID_HERE - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY_HERE - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_AWS_STORAGE_BUCKET_NAME=YOUR_AWS_S3_BUCKET_NAME_HERE - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} SENDGRID_USERNAME=YOUR_SENDGRID_USERNAME - ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} SENDGRID_PASSWORD=YOUR_SENDGRID_PASSWORD - ssh -t dokku@yourservername.com dokku run {{cookiecutter.repo_name}} python {{cookiecutter.repo_name}}/manage.py migrate - ssh -t dokku@yourservername.com dokku run {{cookiecutter.repo_name}} python {{cookiecutter.repo_name}}/manage.py createsuperuser - -When deploying via Dokku make sure you backup your database in some fashion as it is NOT done automatically. +The instructions for deployment can be found at https://{{ cookiecutter.repo_name }}.readthedocs.org/en/latest/deploy.html \ No newline at end of file diff --git a/{{cookiecutter.repo_name}}/docs/deploy.rst b/{{cookiecutter.repo_name}}/docs/deploy.rst index 1e642c798..50fc2065a 100644 --- a/{{cookiecutter.repo_name}}/docs/deploy.rst +++ b/{{cookiecutter.repo_name}}/docs/deploy.rst @@ -1,4 +1,69 @@ Deploy ======== -This is where you describe how the project is deployed in production. +It is possible to deploy to Heroku or to your own server by using Dokku, an open source Heroku clone. + +Heroku +^^^^^^ + +Run these commands to deploy the project to Heroku: + +.. code-block:: bash + + heroku create --buildpack https://github.com/heroku/heroku-buildpack-python + heroku addons:add heroku-postgresql:dev + heroku addons:add pgbackups:auto-month + heroku addons:add sendgrid:starter + heroku addons:add memcachier:dev + heroku pg:promote DATABASE_URL + heroku config:set DJANGO_CONFIGURATION=Production + heroku config:set DJANGO_SECRET_KEY=RANDOM_SECRET_KEY_HERE + heroku config:set DJANGO_AWS_ACCESS_KEY_ID=YOUR_AWS_ID_HERE + heroku config:set DJANGO_AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY_HERE + heroku config:set DJANGO_AWS_STORAGE_BUCKET_NAME=YOUR_AWS_S3_BUCKET_NAME_HERE + git push heroku master + heroku run python {{cookiecutter.repo_name}}/manage.py migrate + heroku run python {{cookiecutter.repo_name}}/manage.py createsuperuser + heroku open + +Dokku +^^^^^ + +You need to make sure you have a server running Dokku with at least 1GB of RAM. Backing services are +added just like in Heroku however you must ensure you have the relevant Dokku plugins installed. + +.. code-block:: bash + + cd /var/lib/dokku/plugins + git clone https://github.com/rlaneve/dokku-link.git link + git clone https://github.com/jezdez/dokku-memcached-plugin memcached + git clone https://github.com/jezdez/dokku-postgres-plugin postgres + dokku plugins-install + +You can specify the buildpack you wish to use by creating a file name .env containing the following. + +.. code-block:: bash + + export BUILDPACK_URL= + +You can then deploy by running the following commands. + +.. code-block:: bash + + git remote add dokku dokku@yourservername.com:{{cookiecutter.repo_name}} + git push dokku master + ssh -t dokku@yourservername.com dokku memcached:create {{cookiecutter.repo_name}}-memcached + ssh -t dokku@yourservername.com dokku memcached:link {{cookiecutter.repo_name}}-memcached {{cookiecutter.repo_name}} + ssh -t dokku@yourservername.com dokku postgres:create {{cookiecutter.repo_name}}-postgres + ssh -t dokku@yourservername.com dokku postgres:link {{cookiecutter.repo_name}}-postgres {{cookiecutter.repo_name}} + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_CONFIGURATION=Production + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_SECRET_KEY=RANDOM_SECRET_KEY_HERE + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_AWS_ACCESS_KEY_ID=YOUR_AWS_ID_HERE + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY_HERE + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} DJANGO_AWS_STORAGE_BUCKET_NAME=YOUR_AWS_S3_BUCKET_NAME_HERE + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} SENDGRID_USERNAME=YOUR_SENDGRID_USERNAME + ssh -t dokku@yourservername.com dokku config:set {{cookiecutter.repo_name}} SENDGRID_PASSWORD=YOUR_SENDGRID_PASSWORD + ssh -t dokku@yourservername.com dokku run {{cookiecutter.repo_name}} python {{cookiecutter.repo_name}}/manage.py migrate + ssh -t dokku@yourservername.com dokku run {{cookiecutter.repo_name}} python {{cookiecutter.repo_name}}/manage.py createsuperuser + +When deploying via Dokku make sure you backup your database in some fashion as it is NOT done automatically. \ No newline at end of file diff --git a/{{cookiecutter.repo_name}}/docs/index.rst b/{{cookiecutter.repo_name}}/docs/index.rst index f145b12af..31ee47af3 100644 --- a/{{cookiecutter.repo_name}}/docs/index.rst +++ b/{{cookiecutter.repo_name}}/docs/index.rst @@ -14,7 +14,6 @@ Contents: readme install deploy - tests contributing authors diff --git a/{{cookiecutter.repo_name}}/docs/install.rst b/{{cookiecutter.repo_name}}/docs/install.rst index 1bc03335d..e0bf4f851 100644 --- a/{{cookiecutter.repo_name}}/docs/install.rst +++ b/{{cookiecutter.repo_name}}/docs/install.rst @@ -1,4 +1,77 @@ Install ========= -This is where you write how to get a new laptop to run this project. +Getting up and running +---------------------- + +The steps below will get you up and running with a local development environment. We assume you have the following installed: + +* pip +* virtualenv +* PostgreSQL + +First make sure to create and activate a virtualenv_, then open a terminal at the project root and install the requirements for local development:: + + $ pip install -r requirements/local.txt + +.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/ + +You can now run the usual Django ``runserver`` command (replace ``yourapp`` with the name of the directory containing the Django project):: + + $ python yourapp/manage.py runserver + +The base app will run but you'll need to carry out a few steps to make the sign-up and login forms work. These are currently detailed in `issue #39`_. + +.. _issue #39: https://github.com/pydanny/cookiecutter-django/issues/39 + +**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 the included Grunt task. + +Make sure that nodejs_ is installed. Then in the project root run:: + + $ npm install grunt + +.. _nodejs: http://nodejs.org/download/ + +Now you just need:: + + $ grunt serve + +The base app will now run as it would with the usual ``manage.py runserver`` but with live reloading and Sass compilation enabled. + +To get live reloading to work you'll probably need to install an `appropriate browser extension`_ + +.. _appropriate browser extension: http://feedback.livereload.com/knowledgebase/articles/86242-how-do-i-install-and-use-the-browser-extensions- + +It's time to write the code!!! + + +Settings +------------ + +{{cookiecutter.project_name}} 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. + +For configuration purposes, the following table maps the '{{cookiecutter.project_name}}' environment variables to their Django setting: + +======================================= =========================== ============================================== =========================================== +Environment Variable Django Setting Development Default Production Default +======================================= =========================== ============================================== =========================================== +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 +DJANGO_CACHES CACHES locmem memcached +DJANGO_DATABASES DATABASES See code See code +DJANGO_DEBUG DEBUG True False +DJANGO_EMAIL_BACKEND EMAIL_BACKEND django.core.mail.backends.console.EmailBackend django.core.mail.backends.smtp.EmailBackend +DJANGO_SECRET_KEY SECRET_KEY CHANGEME!!! 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 +DJANGO_SECURE_FRAME_DENY SECURE_FRAME_DENY n/a True +DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS HSTS_INCLUDE_SUBDOMAINS n/a True +DJANGO_SESSION_COOKIE_HTTPONLY SESSION_COOKIE_HTTPONLY n/a True +DJANGO_SESSION_COOKIE_SECURE SESSION_COOKIE_SECURE n/a False +======================================= =========================== ============================================== =========================================== + +* TODO: Add vendor-added settings in another table \ No newline at end of file