From dbe49dc38c160062421cfe140e2f4e471405ea96 Mon Sep 17 00:00:00 2001 From: Dylan DiGeronimo Date: Sun, 26 Jan 2020 19:33:08 -0500 Subject: [PATCH] Update documentation --- README.md | 55 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index e01f11b..5a34418 100644 --- a/README.md +++ b/README.md @@ -10,29 +10,29 @@ Forked from Sean Redmond's [original protype](https://github.com/seanredmond/cce - Python 3.7 - Pipenv -## Using Pipenv +### Why Pipenv? Using a virtual environment is very important for ensuring that all work is done in a standardized Python environment. In order to simplify using a virtual environment as well as to give us the ability to create deterministic builds, we use [Pipenv](https://realpython.com/pipenv-guide/). -### Installing Pipenv +## Installing Pipenv -#### Mac +### Mac `brew install pipenv` *Note: Mac users can also install through Pip, but using Homebrew is recommended.* -#### Other systems +### Other systems `pip install --user pipenv` *Note: You may have versions of Pip installed for both Python 2 and 3. If so, your Python 3 Pip will be called pip3. Check if this is the case by running `pip --version` and `pip3 --version`.* -### First time package install +## Installing all dependencies and creating the virtual environment -Run `pipenv install` in the project's main directory. +Run `pipenv install` in the project's main directory. If installing for development purposes, rather than deployment, add the `--dev` flag to install required development packages as well. -### Installing new packages +## Installing new packages In the project directory, use `pipenv install` the same way you would use `pip install`. The package will be installed in the virtual environment, and the Pipfile will be updated. @@ -42,25 +42,25 @@ To specify a specific package version: `pipenv install flask==0.12.1` To install packages for development purposes (e.g. ones that aren't required to build and run the project, but are useful for working on it), you can use the --dev flag. For example, `pipenv install pytest --dev`. -### Activating the virtual environment +## Activating the virtual environment To activate the virtual environment in your current shell, run `pipenv shell`. The virtual environment will be indicated by a change to your terminal prompt. -### "Locking" the virtual environment +## "Locking" the virtual environment -To ensure a deterministic build and "lock" the versions of packages and their subdependencies, run `pipenv lock`. This will ensure Pipfile.lock is up to date. Do this when any changes are made for the production environment. +To ensure a deterministic build and "lock" the versions of packages and their subdependencies, run `pipenv lock`. This will ensure Pipfile.lock is up to date. Do this when you intend to push any changes to the production environment. -### Remove an unneeded package +## Remove an unneeded package To remove a package from the Pipfile and uninstall it from your virtual environment, use `pipenv uninstall`. For example, to remove beautifulsoup: `pipenv uninstall beautifulsoup` -### Run a command in the virtual environment without activating it +## Run a single command in the virtual environment without activating it -`pipenv run [command_goes_here]` +`$ pipenv run [command_goes_here]` -### Closing the virtual environment +## Closing the virtual environment After you have activated the virtual environment, press `ctrl-d` to exit. Your terminal prompt should return to its original appearance. @@ -68,15 +68,30 @@ After you have activated the virtual environment, press `ctrl-d` to exit. Your t ## Deploying the project locally -After activating the virtual environment, run the following command from within the root directory of the project: +After activating the virtual environment, run the following commands from within the root directory of the project: -`gunicorn -w=4 wsgi:app` + + $ export FLASK_ENV=development -This will run the Flask application on a Gunicorn WSGI server. You can then go to [localhost:8000](localhost:8000) to use the application. +*(This is optional, but enables useful debugging tools)* + + $ flask run + +The Flask app will then be running at [localhost:5000](localhost:5000). To close the application, end the process with `ctrl-c` in your terminal. -**TODO:** +## Running Tests -- Update Gunicorn config file to automatically specify number of worker processes -- Address reinstallation of venv (pipenv --rm, pipenv install) \ No newline at end of file +In the root directory of the project, run `python -m pytest`. This will run the entire test suite. New test functions and files must be contained in the `tests/` directory. + +## Troubleshooting + + The 'pipenv==20XX.XX.XX' distribution was not found and is required by the application + +Reinstall Pipenv, with the methods specified [above](#Installing-Pipenv). + + Warning: Your Pipfile requires python_version 3.7, but you are using X.X.X (/Users/...). + $ pipenv check will surely fail. + +This means your Python installation has changed since you first created the venv with `pipenv install`. Delete it using `pipenv --rm`, then [rebuild it](#Installing-all-dependencies-and-creating-the-virtual-environment). \ No newline at end of file