This is an example start project for Kickstart Coding Django projects.
It provides a solid foundation for building a Django project that's ready to launch to Heroku or similar web-hosting service.
-
Clean, simple, and up-to-date: Only a few changes from the officia
django-admin startproject
-
Bootstrap 4: It's all set-up with Bootstrap 4.4.1 CSS, a few example pages, and
django-bootstrap4
for easily bootstrap-based forms -
Accounts:
- Log-in and sign-up pages
- Custom user class
- User profile page and user editing page
-
Heroku support: It's one
git push
away from publishing to the world -
Pipenv: It's set-up to use Pipfile
-
Code standards: This was created to be a happy medium between the default
django-admin
starting template and heavier weight scaffolding such as Audrey / Daniel Greenfield's Django Cookiecutter, which might be better for larger projects -
Easy development:
- Separate
local
andproduction
settings - Use Sqlite locally and postgres in production
- While for bigger projects production / dev parity is vitally important, this is great for getting started with smaller projects
- Separate
-
Misc nice stuff:
django-debug-toolbar
-- great debugging tool- Error pages
-
This is for new Python/Django programmers, including coding class students who want a solid start for a Django project that uses SQLite when developing locally, and is ready to deploy Heroku provisioned Postgres database.
-
The documentation assumes you already have fundamental Python, Django, Bash and Heroku knowledge. If you are new to Heroku, read our Heroku Getting Started guide. If you are new to Postgres, read our Postgres Getting Started guide .
-
The documentation does not explicitly support Windows. It assumes you use either macOS or a GNU/Linux distribution such as Ubuntu. That said, it might work.
This was originally created for Kickstart Coding, the cutting-edge, personalized, and affordable "custom-paced" full-stack online coding program. Learn more and enroll in our Python / Django, JavaScript / React web development, and career development courses here.
- Prereqs: 1) You have Pipenv
installed. 2) You
have Django admin installed globally (macOS type
pip3 install django
, Ubuntu GNU/Linux, typesudo pip3 install django
)
- Assuming
mycoolproject
is the name of your project, you should start a new project using this template as follows:
django-admin startproject --template=https://github.com/kickstartcoding/django-kcproject-starter/archive/master.zip mycoolproject
- Go into the newly created project, and use
pipenv
to get your virtualenv setup:
cd mycoolproject
pipenv shell
pipenv install --skip-lock --dev
Note: It's probably okay if you get errors while installing psycopg2
and/or gunicorn
, such as 'ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.'
. These
packages are not needed for development. That's why we have --skip-lock
specified to prevent these errors from stopping the installation.
- This starter project does not include migrations. Make migrations as such:
python manage.py makemigrations accounts
- Run the migrations to actually create the SQLite database:
python manage.py migrate
- Get the server running:
python manage.py runserver
-
Create a new repo on GitHub, and BE SURE TO NOT check "initialize with README.md" or
.gitignore
or anything. You want to make a truly blank repo for these steps to work without a hiccup. Just fill in the name and description, and nothing else. -
Now, initialize and push the code we have by running this in the command-line:
ls # Ensure you are "next to" the manage.py, etc
git init # Initalize this
git add -A # Add all your files
git commit -m "first" # Make a commit
- Finally, link up your local repository with the git one, and push. Follow
the instructions provided on the github.com page. They will look a little like
this, except instead of
janeqhacker/mycoolproject
it will be whatever your username is and your repo name is:
git remote add origin [email protected]:janeqhacker/mycoolproject.git
git push -u origin master
Directory structure description below:
[name_of_project]/
- config/
- base.py # Stores most settings
- local.py # Stores settings only for local dev
- production.py # Stores settings only used by production (e.g. Heroku)
- urls.py # Global urls.py, in turn includes urls.py in apps
- apps/ # A directory to store all our custom apps
- accounts/ # An example custom app that includes sign-up and log-in
- models.py # Customized user class is here
- urls.py # URLs for sign-up and log-in pages
- views.py # Views for sign-up and log-in pages
- forms.py # Form for editing user profile, sign-up
- templates/ # Templates for user profile stuff
- core/ # An example custom app that has some static pages
- static/ # Static files
- templates/ # Core templates, including base templates
- etc
- manage.py # Entry point
- Pipfile # Development requirements
- Creating a new Heroku app & Postgres Database (only need to do this once per Heroku):
heroku create # Create a Heroku app (only run this if you haven't already)
heroku addons:create heroku-postgresql:hobby-dev
- Optional: Confirm that the database is working by connecting to it with the
command-line client (
Ctrl+D
to exit):
heroku pg:psql
- Push to Heroku
git push heroku master
- Run the migrations on the remote Postgres database. That can be done as follows:
heroku run python manage.py migrate
-
Your site should work! View it in your browser.
-
You'll also want to add a
SECRET_KEY
to Heroku to make your site secure:
heroku config:set SECRET_KEY=randomly hit keys
NOTE: Where it says "randomly hit keys", do just that! Just type a really long random series of letters and numbers. You'll never have to remember it again.
If you get an error like this while trying to do the initial startproject
:
CommandError: couldn't download URL https://github.com/kickstartcoding/django-kcproject-starter/archive/master.zip to master.zip
<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108)>
-
Go to https://github.com/kickstartcoding/django-kcproject-starter
-
Click the button
[Clone or download v]
, then click[Download Zip]
-
Save the
django-kcproject-starter-master.zip
file somewhere, such as in your~/Downloads
directory, or in the directory you are working -
Now, run the same command as before (again using
mycoolproject
as the example name), except referencing the downloaded copy. Example commands below:
# If you saved it in ~/Downloads, then do:
django-admin startproject --template=~/Downloads/django-kcproject-starter-master.zip mycoolproject
# If you saved it in the current directory:
django-admin startproject --template=./django-kcproject-starter-master.zip mycoolproject
This can happen to some users, often on macOS, and has to do with SSL certificates and/or Python3 having some installation issues. To properly solve this issue, you may need to upgrade your Python3 installation, and/or add updated certificates. This can be tricky and OS-specific, so consider using the work-around above.
You might get large error messages while installing these packages. It might look like:
'ERROR: Command errored out with exit status 1: python setup.py egg_info
Check the logs for full command output.'
Ignore it, and keep on developing!
These packages are not needed for development. Likely everything else will work
fine, and you won't run into any issues while developing, since the local
development set-up is using Sqlite, not Postgres, and the local development
server doesn't use gunicorn
.
For GNU/Linux based systems, psycopg2
this can often be properly solved by
simply installing the Postgres client locally on your operating system (e.g.
sudo apt install postgres
). For Macintosh-based operating systems, the
solution might be more involved, and we'd recommend searching for Mac-specific
answers about Python3 psycopg2
failing to compile.
If you get an error like this:
remote: conn.setdefault('ATOMIC_REQUESTS', False)
remote: AttributeError: 'NoneType' object has no attribute 'setdefault'
That might mean your Postgres database isn't yet created, and that you possibly skipped that step:
heroku addons:create heroku-postgresql:hobby-dev
- Add env variables to Heroku as such:
heroku config:set MAILGUN_API_KEY=(YOUR API KEY AS SPECIFIED BY MAILGUN)
heroku config:set MAILGUN_DOMAIN=(YOUR DOMAIN AS SPECFIEID BY MAILGUN)
- Install anymail
pipenv install django-anymail
-
Then, add the following to your
production.py
:# Anymail (Mailgun) # ------------------------------------------------------------------------------ # https://anymail.readthedocs.io/en/stable/installation/#installing-anymail INSTALLED_APPS += ['anymail'] EMAIL_BACKEND = 'anymail.backends.mailgun.EmailBackend' # https://anymail.readthedocs.io/en/stable/installation/#anymail-settings-reference ANYMAIL = { 'MAILGUN_API_KEY': os.environ.get('MAILGUN_API_KEY'), 'MAILGUN_SENDER_DOMAIN': os.environ.get('MAILGUN_DOMAIN') }
If you want to be able to upload files and not have them be wiped out each time you launch, you'll need to set up Amazon S3 or an equivalent competing Object Store (such as Digital Ocean's Object Store).
Setup AWS and get your keys by following this guide:
https://devcenter.heroku.com/articles/s3
- This assumes familiarity with React and Create React App (CRA).
- These instructions will work with other frontend frameworks as well that follow a similar development pattern as CRA, with only a few tweaks necessary based on the commands they expect and the files and directories their build-tools generate
- Start a new React app called "frontend", by running the following command in
the same directory as
manage.py
:
npx create-react-app frontend
- Build the frontend. The goal here is to just have the "sample app" that
comes with CRA built and residing in the
build/
directory:
cd frontend
npm run build
- Configure Django to serve up React's compiled JS, CSS, etc as additional static files. Put this at the end of your "base.py" settings file:
STATICFILES_DIRS = [
os.path.join(BASE_DIR, '..', 'frontend', 'build', 'static'),
]
- Create a view-function in Django to serve up the frontend's "index.html" in
the build directory to "kick things off". Open up
apps/core/views.py
and add the following code:
from django.http import HttpResponse
def react_app(request):
index_contents = open('./frontend/build/index.html').read()
return HttpResponse(index_contents)
- Create a URL route for your new view-function. Open up
apps/core/urls.py
and add the following URL path to the end of the list, before the]
:
path('app/', views.react_app),
-
Now, run the Django server as you normally would, and navigate to
localhost:8000/app/
-- if you did everything correctly, you should see the CRA sample application in your browser! -
If you are using React Router, you will want Django to serve up React in lieu of a 404 page, to permit ANY route to go to React Router (not just
app/
or the one you specify). Go into the project-level urls.py, and add the following to the very end of the file:
from django.urls import re_path
from app.core import views
urlpatterns += [re_path(r'.*', views.react_app)]
Tips:
- To keep on using CRA's test server during development so you get
live-reloading, running both Django and node simultaneously. To do this,
you'll have to configure CRA's proxy setting, by editing
frontend/package.json
to include"proxy": "http://localhost:8000/",
- After changes to your front-end, be sure to run
npm run build
to regenerate the compiled version of your JS. - When deploying to production, make sure that the
build/
directory gets included in Git (remove it from .gitignore in the root directory and thefrontend/
directory if it happens to be in either)