rearranging the docs and readme info, so that the readme points to the docs links

This commit is contained in:
Felipe Arruda Pontes 2015-03-01 11:07:25 -03:00
parent 97870eab85
commit dd5e077e2b
5 changed files with 147 additions and 159 deletions

View File

@ -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 $ git clone https://github.com/your_username_here/{{ cookiecutter.repo_name }}.git
3. Install your local copy into a `virtualenv <http://virtualenv.readthedocs.org/en/latest/>`_. Assuming you have `virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ installed, this is how you set up your fork for local development:: 3. Install your local copy following the instructions in the docs https://{{ cookiecutter.repo_name }}.readthedocs.org/en/latest/install.html
$ mkvirtualenv {{ cookiecutter.repo_name }}
$ cd {{ cookiecutter.repo_name }}/
$ python setup.py develop
4. Create a branch for local development:: 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. 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 5. Commit your changes and push your branch to GitHub::
$ 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::
$ git add . $ git add .
$ git commit -m "Your detailed description of your changes." $ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature $ 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 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. 1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put 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 your new functionality into a function with a docstring.
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 }}

View File

@ -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. {{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: 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
======================================= =========================== ============================================== ===========================================
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
Getting up and running 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: 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.
* 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!!!
Deployment Deployment
------------ ------------
It is possible to deploy to Heroku or to your own server by using Dokku, an open source Heroku clone. The instructions for deployment can be found at https://{{ cookiecutter.repo_name }}.readthedocs.org/en/latest/deploy.html
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=<repository>
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.

View File

@ -1,4 +1,69 @@
Deploy 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=<repository>
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.

View File

@ -14,7 +14,6 @@ Contents:
readme readme
install install
deploy deploy
tests
contributing contributing
authors authors

View File

@ -1,4 +1,77 @@
Install 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