From 315e81ea81848f7bdcb9b6a46a8f6fa59f3e91bc Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:22:29 -0700 Subject: [PATCH] add installation instructions --- README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5d3c1e6 --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# Django REST Framework Contacts API Template + +## Description + +This is a single model full CRUD API for contacts using Python and Django. + +> This is an **api only**. I would suggest consuming this API using React as a _separate server_ by using [create-react-app](https://reactjs.org/docs/create-a-new-react-app.html). + +### Contacts Properties: + +|Property | Type | Default | +|---|---|---| +| id | integer | assigned by db | +| name | string | n/a | +| age | int | n/a | + +### Contacts Routes: + +|Endpoint | Action | +|---|---| +| `/api/contacts` | GET (Index) | +| `/api/contacts/:id` | GET (Show) | +| `/api/contacts` | POST | +| `/api/contacts/:id` | DELETE | +| `/api/contacts/:id` | PUT | + +## System Requirements + +- Python 3 +- pipenv + +### Installation + +If you don't have either of the above, please install them. + +
Python3 Installation

+ +#### Python Installation + +1. Check what python version you have on your computer by running: `python -V` +1. If you're not on a version of Python that is 3 or greater, install python 3 with homebrew: + - `brew install python3` + - Note: in order to use this installed python3, you will have to use `python3` whenever running a python command + +

+ +
pipenv Installation

+ +#### pipenv Installation + +To build your app, we're going to be building a virtual environment. In order to manage our dependencies and our virtual environment, we're going to use [pipenv](https://pipenv.pypa.io/en/latest/). + +1. Check if you have pipenv by running: `pipenv --version` +1. If you do not have it, install it with homebrew: + - `brew install pipenv` + +

+ +--- + +## Get Set Up Locally + +### On your Browser + +1. Fork this repository to your account + +### In your Terminal + +1. Clone **your fork** of the repo onto your computer anywhere that is not a git repo +1. `cd` into the repo +1. Touch a `.env` into the root of your project and add a SECRET_KEY value. See the .env.sample file for an example +1. Install all the required packages by running: `pipenv install` +1. Activate the virtual environment by running: `pipenv shell` + - NOTE: To exit the shell gracefully whenever you're done working, use `exit` +1. Create the `django_contacts` psql database and user by running: `psql -U postgres -f settings.sql` + - You can find the database name and username/password inside the settings.sql file +1. Apply the migrations by running: `python3 manage.py migrate` +1. Make a superuser for your app, this will allow you to work directly with your database on the browser without having to use Postman + - In the pipenv shell, run `python3 manage.py createsuperuser` and follow the instructions +1. Start the Django server by running the following inside the pipenv shell: `python3 manage.py runserver` + +### On your Browser + +1. Go to `localhost:8000/api/contacts`. You should see the Django REST Framework interface like so: +![](https://imgur.com/V6SvjaX.png) +1. Click the `Log In` on the top right corner and use the username/password you created when making the superuser +1. You should now be able to add / delete / edit / read contacts directly from your browser + +--- + +## Making Changes + +### Updating / Creating Models + +1. If you make any changes to the `contacts_api/models.py` file, you will need to make and run a migration to apply the changes. Do the following commands while _inside the pipenv shell_ + 1. Make the migration: `python3 manage.py makemigrations` + 1. Apply the migration: `python3 manage.py migrate` + +--- + +## Set Up for Heroku Deployment + +### In Terminal +1. Create a heroku app from the root of your project folder, run: `heroku create` + - The above command will randomly generate a name for you, if you want to name your app something specific run: `heroku create urlNameYouWantHere` + +### In your Code Editor + +1. Copy the heroku url that was created (without the `https://`), go to your `django_rest_api/settings.py` and add it into the `ALLOWED_HOSTS` + - e.g. + ![](https://imgur.com/AVlB8kK.png) + +### On the Browser + +1. Go to your heroku dashboard for the heroku project you just created +1. Click on Configure Add-Ons +1. Search for Heroku Postgres and add it +1. Go to the Settings, Reveal Config Vars, add a config var for SECRET_KEY and anything else you have in your .env file + +### In Terminal + +1. `pipenv lock` to ensure your pipfile.lock is up to date +1. `git add -A` +1. `git commit -m "heroku deployment"` +1. `git push heroku master` +1. Once it builds successfully, run `heroku run bash` +1. While in heroku bash, apply the migrations to the heroku project by running: `python manage.py migrate` +1. Still in heroku bash, create a superuser for the heroku project by running `python + - To exit heroku bash, run `exit` + +### In Browser + +1. After the migrations finish, you should now be able to open the heroku app and use this deployed version as your backend API + - Don't forget to go to `/api/contacts` +1. Remember that your heroku database is separate from your local database, so there should not be any data on the first load. + - You can add data by logging in with the heroku superuser you created