Bookstore Window

Search for books and view the results as in a store window.

Development

Here are the steps to take to work on this project. These steps were developed on a macOS with homebrew as a program manager.

Install python environment

The following commands create a python virtual environment using the correct version of python, and all of the required packages installed.

# Install pyenv and pipenv
brew install pyenv pipenv

# Activate pyenv to pin specific versions of python.
eval "$(pyenv init -)"

# Create a virtual environment for the project with pipenv.
# pipenv will download the required version of python using pyenv if necessary.
# The required packages are stored in the "Pipfile".
pipenv install --python 3.6.7 --dev

Set environment variables

Running the app locally requires the following environment variables:

GOOGLE_API_KEY=XXXXXXX
DEBUG=1

To set these environment variables, run the "bin/setup-env.py" script in the project's virtualenv to create a ".env" file containing the required environment variables. The script will prompt the user for the required environment variables and write them as KEY=VALUE to an ".env" file.

pipenv run bin/setup-env.py  # creates ".env"

Note: The ".env" file is expected by pipenv and heroku.

Install web driver for user tests

The user tests use Selenium and a headless Chrome web driver. The web driver for Chrome need to be installed separately.

# on macOS
brew cask install chromedriver

# on ubuntu
sudo apt install chromium-chromedriver

When the chromedriver is installed on Ubuntu, it is not on the user's path by default, in which case a full path to the executable is needed when initializing web drivers for tests. The path to the chromedriver may be something like "/usr/lib/chromium-browser/chromedriver".

Testing

The full test suite requires a Google API Key and chromedriver. Requests are made once and cached using betamax.

Running the tests locally

./manage.py test window        # does not require GOOGLE_API_KEY
./manage.py test google_books  # requires GOOGLE_API_KEY
./manage.py test user_tests    # requires chromedriver and GOOGLE_API_KEY
./manage.py test               # run all tests

Although the cached responses could be committed to the repo as fixtures so that the tests were reproducible without a Google API Key, the Google API Key is stored in the cached responses. Since this is a public project and the Google API Key is private, the fixtures are not committed to the repo and must be regenerated by each developer.

Running the tests on a Vagrant machine

To run the tests on a vagrant machine, install Vagrant and VirtualBox, and run vagrant up. The provisioning is done with Ansible, which is included as a "dev" requirement in the "Pipfile".

# Install the required programs
brew install vagrant
brew cask install virtualbox

# Download the expected box
vagrant box add geerlingguy/ubuntu1804

# Spin up a VM, provision the app, and run all the tests
vagrant up

# Provision the app and run all the tests
vagrant provision

Note: If the Ansible task "Run the django tests" returns "ok", it means all the tests passed.

Running the app

Run the app on a local server

# Activate the virtual environment, reading environment variables from the ".env" file.
pipenv shell

# Collect static files and apply DB migrations
./manage.py collectstatic
./manage.py migrate

# Run the app on the django development server
./manage.py runserver

The following commands configure Heroku for deployment.

# Install the heroku command line tool
brew install heroku/brew/heroku

# Authenticate with the heroku client
heroku login

# List any running apps
heroku apps

Run the app on a Heroku virtual server

# Run the app on a Heroku virtual server
# Reads environment variables from ".env"
heroku local

# Run the user tests against the Heroku virtual server
STAGING_SERVER=http://0.0.0.0:5000 pipenv run ./manage.py test user_tests

Deploying the app with Heroku

# Creates a heroku machine and points a git remote to it
heroku apps:create

# If a Heroku app has already been created, set a git remote to point to it
heroku git:remote -a APPNAME

# Set the required virtual environment variables on the host machine.
heroku config:set GOOGLE_API=XXXXXXXX
heroku config:set SECRET_KEY=XXXXXXXX

# Deploy the app by pushing to the git remote heroku
git push heroku master:master

# Run the migration script on the heroku machine to initialize the DB tables.
heroku run python manage.py migrate

Accessing the Postgres database

heroku pg:info  # view db info
heroku pg:psql  # jump into a db session
heroku pg:reset # reset the db

Obtaining a Google Books API Key

Using the Google Books API requires requires an API key, which was created via the Google Developer Console.

pedmiston / bookstorewindow