mirror of
https://github.com/cookiecutter/cookiecutter-django.git
synced 2024-11-22 17:47:08 +03:00
195 lines
6.5 KiB
ReStructuredText
195 lines
6.5 KiB
ReStructuredText
cookiecutter-django
|
|
=======================
|
|
|
|
.. image:: https://requires.io/github/pydanny/cookiecutter-django/requirements.svg?branch=master
|
|
:target: https://requires.io/github/pydanny/cookiecutter-django/requirements/?branch=master
|
|
:alt: Requirements Status
|
|
|
|
.. image:: https://travis-ci.org/pydanny/cookiecutter-django.svg?branch=master
|
|
:target: https://travis-ci.org/pydanny/cookiecutter-django?branch=master
|
|
:alt: Build Status
|
|
|
|
A cookiecutter_ template for Django.
|
|
|
|
.. _cookiecutter: https://github.com/audreyr/cookiecutter
|
|
|
|
Please update your version of cookiecutter!
|
|
--------------------------------------------
|
|
|
|
This cookiecutter template uses features that exists only in cookiecutter 0.9.0 or higher.
|
|
|
|
Features
|
|
---------
|
|
|
|
* For Django 1.8
|
|
* Twitter Bootstrap_ 3
|
|
* AngularJS_
|
|
* 12-Factor_ based settings via django-environ_
|
|
* Optimized development and production settings
|
|
* Registration via django-allauth_
|
|
* Procfile_ for deploying to Heroku
|
|
* Grunt build for compass and livereload
|
|
* Basic e-mail configurations for send emails via SendGrid_
|
|
* Media storage using Amazon S3
|
|
* Serve static files from Amazon S3 or Whitenoise_ (optional)
|
|
|
|
.. _Bootstrap: https://github.com/twbs/bootstrap
|
|
.. _AngularJS: https://github.com/angular/angular.js
|
|
.. _django-environ: https://github.com/joke2k/django-environ
|
|
.. _12-Factor: http://12factor.net/
|
|
.. _django-allauth: https://github.com/pennersr/django-allauth
|
|
.. _django-avatar: https://github.com/jezdez/django-avatar/
|
|
.. _Procfile: https://devcenter.heroku.com/articles/procfile
|
|
.. _SendGrid: https://sendgrid.com/
|
|
.. _Whitenoise: https://whitenoise.readthedocs.org/
|
|
|
|
|
|
Constraints
|
|
-----------
|
|
|
|
* Only maintained 3rd party libraries are used.
|
|
* PostgreSQL everywhere (9.0+)
|
|
* Environment variables for configuration (This won't work with Apache/mod_wsgi).
|
|
|
|
|
|
Usage
|
|
------
|
|
|
|
Let's pretend you want to create a Django project called "redditclone". Rather than using `startproject`
|
|
and then editing the results to include your name, email, and various configuration issues that always get forgotten until the worst possible moment, get cookiecutter_ to do all the work.
|
|
|
|
First, get cookiecutter. Trust me, it's awesome::
|
|
|
|
$ pip install cookiecutter
|
|
|
|
Now run it against this repo::
|
|
|
|
$ cookiecutter https://github.com/pydanny/cookiecutter-django.git
|
|
|
|
You'll be prompted for some questions, answer them, then it will create a Django project for you.
|
|
|
|
|
|
**Warning**: After this point, change 'Daniel Greenfeld', 'pydanny', etc to your own information.
|
|
|
|
It prompts you for questions. Answer them::
|
|
|
|
Cloning into 'cookiecutter-django'...
|
|
remote: Counting objects: 550, done.
|
|
remote: Compressing objects: 100% (310/310), done.
|
|
remote: Total 550 (delta 283), reused 479 (delta 222)
|
|
Receiving objects: 100% (550/550), 127.66 KiB | 58 KiB/s, done.
|
|
Resolving deltas: 100% (283/283), done.
|
|
project_name (default is "project_name")? Reddit Clone
|
|
repo_name (default is "Reddit_Clone")? reddit
|
|
author_name (default is "Your Name")? Daniel Greenfeld
|
|
email (default is "Your email")? pydanny@gmail.com
|
|
description (default is "A short description of the project.")? A reddit clone.
|
|
domain_name (default is "example.com")? myreddit.com
|
|
version (default is "0.1.0")? 0.0.1
|
|
timezone (default is "UTC")?
|
|
now (default is "2015/01/13")? 2015/01/16
|
|
year (default is "2015")?
|
|
|
|
|
|
Enter the project and take a look around::
|
|
|
|
$ cd redditclone/
|
|
$ ls
|
|
|
|
Create a GitHub repo and push it there::
|
|
|
|
$ git init
|
|
$ git add .
|
|
$ git commit -m "first awesome commit"
|
|
$ git remote add origin git@github.com:pydanny/redditclone.git
|
|
$ git push -u origin master
|
|
|
|
Now take a look at your repo. Don't forget to carefully look at the generated README. Awesome, right?
|
|
|
|
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/
|
|
|
|
Then, create a PostgreSQL database and add the database configuration using the ``dj-database-url`` app pattern: ``postgres://db_owner:password@dbserver_ip:port/db_name`` either:
|
|
|
|
* in the ``config.settings.common.py`` setting file,
|
|
* or in the environment variable ``DATABASE_URL``
|
|
|
|
|
|
You can now run the usual Django ``migrate`` and ``runserver`` command::
|
|
|
|
$ python manage.py migrate
|
|
|
|
$ python manage.py runserver
|
|
|
|
|
|
**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
|
|
|
|
.. _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!!!
|
|
|
|
"Your Stuff"
|
|
-------------
|
|
|
|
Scattered throughout the Python and HTML of this project are places marked with "your stuff". This is where third-party libraries are to be integrated with your project.
|
|
|
|
Releases
|
|
--------
|
|
|
|
Want a stable release? You can find them at https://github.com/pydanny/cookiecutter-django/releases
|
|
|
|
|
|
Not Exactly What You Want?
|
|
---------------------------
|
|
|
|
This is what I want. *It might not be what you want.* Don't worry, you have options:
|
|
|
|
Fork This
|
|
~~~~~~~~~~
|
|
|
|
If you have differences in your preferred setup, I encourage you to fork this to create your own version.
|
|
Once you have your fork working, let me know and I'll add it to a '*Similar Cookiecutter Templates*' list here.
|
|
It's up to you whether or not to rename your fork.
|
|
|
|
If you do rename your fork, I encourage you to submit it to the following places:
|
|
|
|
* cookiecutter_ so it gets listed in the README as a template.
|
|
* The cookiecutter grid_ on Django Packages.
|
|
|
|
.. _cookiecutter: https://github.com/audreyr/cookiecutter
|
|
.. _grid: https://www.djangopackages.com/grids/g/cookiecutter/
|
|
|
|
Or Submit a Pull Request
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
I also accept pull requests on this, if they're small, atomic, and if they make my own project development
|
|
experience better.
|