From 5df8e1dd108b5914102b217b63bd7bf74af5dbf0 Mon Sep 17 00:00:00 2001 From: Felipe Arruda Pontes Date: Thu, 13 Nov 2014 12:19:26 -0200 Subject: [PATCH 1/4] adding authors, contributing and readme to docs. Also changed 'CONTRIBUTORS.txt' to 'AUTHORS.txt' following the example of cookiecutter-pypackages and also django (they use only 'AUTHORS' there, but I the idea is the same. --- cookiecutter.json | 1 + .../{CONTRIBUTORS.txt => AUTHORS.txt} | 0 {{cookiecutter.repo_name}}/CONTRIBUTING.rst | 111 ++++++++++++++++++ {{cookiecutter.repo_name}}/docs/authors.rst | 1 + .../docs/contributing.rst | 1 + {{cookiecutter.repo_name}}/docs/index.rst | 3 + {{cookiecutter.repo_name}}/docs/readme.rst | 1 + 7 files changed, 118 insertions(+) rename {{cookiecutter.repo_name}}/{CONTRIBUTORS.txt => AUTHORS.txt} (100%) create mode 100644 {{cookiecutter.repo_name}}/CONTRIBUTING.rst create mode 100644 {{cookiecutter.repo_name}}/docs/authors.rst create mode 100644 {{cookiecutter.repo_name}}/docs/contributing.rst create mode 100644 {{cookiecutter.repo_name}}/docs/readme.rst diff --git a/cookiecutter.json b/cookiecutter.json index 4b4858fc4..e2125ebc3 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -2,6 +2,7 @@ "project_name": "project_name is the title of the project.", "repo_name":"repo_name is used for describing the directory structure.", "author_name": "Your Name", + "github_username": "your username", "email": "Your email", "description": "A short description of the project.", "year": "2014", diff --git a/{{cookiecutter.repo_name}}/CONTRIBUTORS.txt b/{{cookiecutter.repo_name}}/AUTHORS.txt similarity index 100% rename from {{cookiecutter.repo_name}}/CONTRIBUTORS.txt rename to {{cookiecutter.repo_name}}/AUTHORS.txt diff --git a/{{cookiecutter.repo_name}}/CONTRIBUTING.rst b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst new file mode 100644 index 000000000..bcb3ce5f8 --- /dev/null +++ b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst @@ -0,0 +1,111 @@ +============ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given. + +You can contribute in many ways: + +Types of Contributions +---------------------- + +Report Bugs +~~~~~~~~~~~ + +Report bugs at https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" +is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "feature" +is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +{{ cookiecutter.project_name }} could always use more documentation, whether as part of the +official {{ cookiecutter.project_name }} docs, in docstrings, or even on the web in blog posts, +articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `{{ cookiecutter.repo_name }}` for local development. + +1. Fork the `{{ cookiecutter.repo_name }}` repo on GitHub. +2. Clone your fork locally:: + + $ git clone git@github.com:your_name_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 + +4. Create a branch for local development:: + + $ git checkout -b name-of-your-bugfix-or-feature + + 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:: + + $ 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. + +Pull Request Guidelines +----------------------- + +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 }} diff --git a/{{cookiecutter.repo_name}}/docs/authors.rst b/{{cookiecutter.repo_name}}/docs/authors.rst new file mode 100644 index 000000000..e122f914a --- /dev/null +++ b/{{cookiecutter.repo_name}}/docs/authors.rst @@ -0,0 +1 @@ +.. include:: ../AUTHORS.rst diff --git a/{{cookiecutter.repo_name}}/docs/contributing.rst b/{{cookiecutter.repo_name}}/docs/contributing.rst new file mode 100644 index 000000000..e582053ea --- /dev/null +++ b/{{cookiecutter.repo_name}}/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/{{cookiecutter.repo_name}}/docs/index.rst b/{{cookiecutter.repo_name}}/docs/index.rst index 3ae55a137..f145b12af 100644 --- a/{{cookiecutter.repo_name}}/docs/index.rst +++ b/{{cookiecutter.repo_name}}/docs/index.rst @@ -11,9 +11,12 @@ Contents: .. toctree:: :maxdepth: 2 + readme install deploy tests + contributing + authors diff --git a/{{cookiecutter.repo_name}}/docs/readme.rst b/{{cookiecutter.repo_name}}/docs/readme.rst new file mode 100644 index 000000000..72a335581 --- /dev/null +++ b/{{cookiecutter.repo_name}}/docs/readme.rst @@ -0,0 +1 @@ +.. include:: ../README.rst From cd09914d6ee741ba968c080295b1339fe78a26a5 Mon Sep 17 00:00:00 2001 From: Felipe Arruda Pontes Date: Mon, 24 Nov 2014 00:52:21 -0200 Subject: [PATCH 2/4] saying that the username in cookiecutter.json is the one from github, as discussed in #154 --- cookiecutter.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookiecutter.json b/cookiecutter.json index e2125ebc3..c6b3dd2d7 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -2,7 +2,7 @@ "project_name": "project_name is the title of the project.", "repo_name":"repo_name is used for describing the directory structure.", "author_name": "Your Name", - "github_username": "your username", + "github_username": "your GitHub username", "email": "Your email", "description": "A short description of the project.", "year": "2014", From 97870eab85d8e209a5c97a4153c61cfaf937b1b1 Mon Sep 17 00:00:00 2001 From: Felipe Arruda Pontes Date: Mon, 24 Nov 2014 00:53:17 -0200 Subject: [PATCH 3/4] adding links for virtualenv and virtualenvwrapper in docs. refs #154 --- {{cookiecutter.repo_name}}/CONTRIBUTING.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.repo_name}}/CONTRIBUTING.rst b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst index bcb3ce5f8..56392e690 100644 --- a/{{cookiecutter.repo_name}}/CONTRIBUTING.rst +++ b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst @@ -60,9 +60,9 @@ Ready to contribute? Here's how to set up `{{ cookiecutter.repo_name }}` for loc 1. Fork the `{{ cookiecutter.repo_name }}` repo on GitHub. 2. Clone your fork locally:: - $ git clone git@github.com:your_name_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. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:: +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 }}/ From dd5e077e2b9f596e0171ec98a81efed8d13d1e2a Mon Sep 17 00:00:00 2001 From: Felipe Arruda Pontes Date: Sun, 1 Mar 2015 11:07:25 -0300 Subject: [PATCH 4/4] rearranging the docs and readme info, so that the readme points to the docs links --- {{cookiecutter.repo_name}}/CONTRIBUTING.rst | 30 +---- {{cookiecutter.repo_name}}/README.rst | 133 +------------------- {{cookiecutter.repo_name}}/docs/deploy.rst | 67 +++++++++- {{cookiecutter.repo_name}}/docs/index.rst | 1 - {{cookiecutter.repo_name}}/docs/install.rst | 75 ++++++++++- 5 files changed, 147 insertions(+), 159 deletions(-) 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