This is a barebones django REST web service project. The idea behind this project was to learn about django REST. The learning process gave way to this starter project which can be used as a starting point for your own django REST project. It comes pre-configured with several python library dependencies that I typically use in a django project such as dj-database-url. The project only contains user authentication (using JWT Tokens) and user profile endpoints. In other words, a user can only login, logout and view their profile info. This makes the project useful for anyone wanting to start out with a simple JWT Token authentication system.

Visit the api docs.

• Getting Started
• Running Locally
  • Database Setup
  • Docker
  • Virtualenv
    • Pre Requisites
    • Create Virtual Environment
    • Create Superuser
• Starting New Project
• Helpful Commands
• Wercker/Heroku Deployment

• The first step to start working on this project is to fork the repository into your personal github account.
• Next, clone the forked repository into your local environment

git clone https://github.com/<your-account-or-organization>/django-rest-starter

For updating your fork from the remote (upstream)

git remote add upstream https://github.com/alexolivas/django-rest-starter

Make sure upstream is configured as expected, should see origin for fork and upstream to main repo

git remote -v

Create an environment variables file

vi .env

Populate it with the following (generate the SECRET_KEY with a tool like 1password: 50 characters)

SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DEBUG=True
DATABASE_URL='postgres://<db-user>@localhost:5432/<db_name>'
ALLOWED_HOSTS=<your_host_url>
CORS_ORIGIN_WHITELIST=<whitelisted-urls>

You can either run the project inside a docker container or inside a virtual environment. If you are actively developing on a local copy of django-rest-starter it is recommended that you use a virtual environment. With a virtual environment you have the benefit of making changes without having to redeploy or start up the web server each time. You can do the same with docker but you have to setup port forwarding.

During the development phase I typically use a postgres database to simulate production as much as possible. These are the database setup instructions I use for my django and django-rest projects.

Install postgres if it is not already in your system

brew install postgresql

PSQL into postgres

psql postgres

Create users and database instances

postgres=# CREATE USER postgres WITH SUPERUSER;
CREATE DATABASE <database-name>;
GRANT ALL PRIVILEGES ON DATABASE <database-name> TO postgres;
CREATE USER <db-user> WITH PASSWORD '<password>';
GRANT ALL PRIVILEGES ON DATABASE <database-name> TO <db-user>;

Docker is an open platform for developers and sysadmins to build, ship, and run distributed applications whether on laptops, data center VMs, or the cloud. Running your local environment inside a docker container will resemble a production environment.

NOTE: Docker usage is still a work in progress, I still need to create the docker files and another docker container for postgres.

To run inside of a Docker container

docker-compose up -d --build --force-recreate

After the container has spinned up, "SSH" into the docker machine

bash -c "clear && docker exec -it djangorest_starter_web_1 sh"

Once inside the docker machine, run the initial database migrations (not using a relational database, using SQLite)

python manage.py migrate

Finally, create a superuser, run the following command and follow the step by step instructions

python manage.py createsuperuser

Virtualenv is a python environment builder and is used together with virtualenvwrapper, which is a set of extensions to the original virtualenv tool. Their primary purpose is to create isolated python environments, which is useful when working with multiple python projects that may have different dependencies.

Install virtualenv

pip install virtualenv

Install virtualenvwrapper

pip install virtualenvwrapper

Create a directory to store details of your future virtual environments (this can be whatever location you'd like but remember it for the next step).

cd ~
mkdir .virtualenvs
mkdir Development/

Edit the bash profile (create it if it doesn't exist)

vi ~/.bash_profile

Add the following to your bash_profile

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Development
source /usr/local/bin/virtualenvwrapper.sh

Run the following command, if it installed correctly you will get a help menu

mkvirtualenv

Last step to be able to work with virtualenvwrapper and environment variables.

vi ~/.virtualenvs/postactivate

Add the following code snippet inside postactivate so that the project's environment variables are available on activate

set -a
. .env
set +a

Create a virtual environment for this project

mkvirtualenv djangorest

After running the command above, your environment is created and you should automatically be inside. You can verify that you are working inside your virtual environment if you bash shell looks like this:

(djangorest)computername:current-directory username$

Within your virtual environment, install the project's requirements

pip install -r requirements.txt

Run the initial database migrations

python manage.py migrate

Run the following command and follow the step by step instructions

python manage.py createsuperuser

If you want to clone this project and use it as a starting point for a new project follow the steps in the getting started section, the only different thing you need to do is name your project differently. After you have followed those steps you need to:

Remove the origin so that you can add your own repository as the new origin

cd <project-name>
git remote rm origin
git remote add origin <your-projects-git-repo>
git push -u origin master

Rename the project (can be different than the project directory name)

mv django-rest-starter/ <project-name>

Replace the original project's name with your project (same name as in step 3) in manage.py

perl -pi -e 's/djangorest/<project-name>/g' manage.py 

Do the exact same thing (same name as in step 3) to the wsgi.py file

perl -pi -e 's/djangorest/<project-name>/g' <project-name>/wsgi.py

Do a final search/replace of djangorest to replace with your project's name using your IDE's search/replace feature.

Commit your project's name changes

git commit -a -m "Renamed Project"

If you are not deploying to Heroku or using wercker as your CI server you can safely delete the following files respectively:

• Procfile
• wercker.yml

Run this command to display the project's dependencies as a tree structure (pipdeptree comes pre-configured as a dependency on this project)

pipdeptree

This project's demo is continuously built by wercker and deployed by the push of a button to heroku. I followed the wercker deployments steps to get the app deployed.