diff --git a/cookiecutter.json b/cookiecutter.json index d1a9775e3..55d92d652 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -2,6 +2,7 @@ "project_name": "project_name", "repo_name": "{{ cookiecutter.project_name|replace(' ', '_') }}", "author_name": "Your Name", + "github_username": "your GitHub username", "email": "Your email", "description": "A short description of the project.", "domain_name": "example.com", 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..605e06a0e --- /dev/null +++ b/{{cookiecutter.repo_name}}/CONTRIBUTING.rst @@ -0,0 +1,89 @@ +============ +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 https://github.com/your_username_here/{{ cookiecutter.repo_name }}.git + +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:: + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + + +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 + +6. 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. diff --git a/{{cookiecutter.repo_name}}/README.rst b/{{cookiecutter.repo_name}}/README.rst index 828cf3294..1de78face 100644 --- a/{{cookiecutter.repo_name}}/README.rst +++ b/{{cookiecutter.repo_name}}/README.rst @@ -11,142 +11,14 @@ 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 ``runserver_plus`` command:: - - $ python {{cookiecutter.repo_name}}/manage.py runserver_plus - -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 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/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 3ae55a137..31ee47af3 100644 --- a/{{cookiecutter.repo_name}}/docs/index.rst +++ b/{{cookiecutter.repo_name}}/docs/index.rst @@ -11,9 +11,11 @@ Contents: .. toctree:: :maxdepth: 2 + readme install deploy - tests + contributing + authors diff --git a/{{cookiecutter.repo_name}}/docs/install.rst b/{{cookiecutter.repo_name}}/docs/install.rst index 1bc03335d..add375ede 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 ``runserver_plus`` command:: + + $ python {{cookiecutter.repo_name}}/manage.py runserver_plus + +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 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