Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #702

Merged
merged 5 commits into from
Oct 27, 2017
Merged

Update README.md #702

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bf57b4c
Update README.md
Oct 12, 2017
cc9bf07
Add website and mailing list links
Oct 12, 2017
77cb738
Use better token place holder
Oct 12, 2017
0d0d4d7
Rephrase line on not having puf file
Oct 12, 2017
a21723d
Clean up a little
Oct 12, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 34 additions & 185 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,206 +1,55 @@
[![Build Status](https://travis-ci.org/OpenSourcePolicyCenter/webapp-public.svg?branch=master)](https://travis-ci.org/OpenSourcePolicyCenter/webapp-public)
About PolicyBrain
---------------------------

Taxbrain Web Application
========================
PolicyBrain provides a platform for open-source policy simulation models. It serves as an interface to powerful models for those who do not want to work directly with the models themselves. PolicyBrain’s primary jobs are to send the user-input to the models, provide feedback if the user-input causes warnings or errors, schedule jobs on available machines, retrieve the results from the models, and deliver the results to the user. Essentially, PolicyBrain provides the infrastructure and resources for the models that it hosts.

The apps that are currently hosted are TaxBrain and Cost-of-Capital Calculator. TaxBrain enables the user to perform static and dynamic analyses on their specified personal income tax reform. Cost-of-Capital Calculator enables the user to perform a static analysis on their specified business tax reform.

PolicyBrain is a Django app which is deployed on Heroku and uses Flask, Celery, and Redis to schedule jobs.

# Deploying To Heroku

Production
----------
Heroku relies upon GIT for deployment. The following commands are for deployment. Before deploying to Heroku make certain to run the following command* locally and commit the changes:

`./manage.py collectstatic --noinput`

###### * Currently this command fails to create the staticfiles dir on Heroku, so this has to be run locally and the changes committed.

Deploy to Heroku:

`git push heroku master`

If any of the models have been updated in a deployment then those changes have to migrated so the database schema is updated. The migration should be created locally, committed, and pushed to Heroku as opposed to running the makemigration command on Heroku. Locally run the following:

`./manage.py makemigrations` or `python manage.py makemigrations` (both commands have the same effect.)

Commit the files that are created.

In order to run those migrations, run the following commands:

`heroku run ./manage.py migrate` or `heroku run python manage.py migrate` (both commands have the same effect.)

Your schema will now be udpated.

*DEBUG*: This should always be False on the production site. Make certain the environment variable DEV_DEBUG is set to anything but the string 'True'. To check what variables are set to in Heroku's environment run the following command:

`heroku config`

This will list all config variables (alternatively go to the Settings section on the Heroku dashboard and click the 'Reveal Config Vars' button.)

Development
-----------
A live development server works exactly the same way as a production server on Heroku does. All commands and configurations are the same. The only difference is that the requirements_dev.txt can be used on this server to have access to the various debugging tools.

Post deployment to a dev server runt he following command in order to install the dev tools (if desired):
`heroku run pip install -r requirement_dev.txt`

The migration commands presented in the Production section also hold true for development. Post deployment make sure to run the migration commands.

*DEBUG*: In order to turn DEBUG on, set the DEV_DEBUG environment variable to the string 'True'. DEBUG will be off id set to anything but 'True'. In order to change the DEV_DEBUG variable use the following command:
`heroku config:set DEV_DEBUG='True'`

The above command will turn DEBUG on. Setting to any other string will turn DEBUG off.
- Website: https://www.ospc.org/
- Mailing List: https://www.freelists.org/list/policybrains_modelers

Release Process
---------------

To review the steps for the release process, see [RELEASE_PROCESS.md](https://github.com/OpenSourcePolicyCenter/webapp-public/blob/master/RELEASE_PROCESS.md)

# Installing Locally
To develop the application locally, you need a script containing the environment variables necessary for communicating with the computation nodes. You should ask your project manager or administrator for this script.

## Installing PostgreSQL
Postgres is used for this project. If PostgreSQL is not installed on your machine follow the instructions in the following links.

OS X:
http://www.postgresql.org/download/macosx/

Ubunutu:
https://help.ubuntu.com/community/PostgreSQL

Windows (should support 7 & 8):
http://www.postgresql.org/download/windows/

## Create database taxcalc
After PostgreSQL has been successfully installed make sure to create the taxcalc database.

For Ubuntu the command is:
```
createdb taxcalc
```

If you need to add a user and grant permissions make sure to have psql installed as well.
Local Deployment Setup
---------------------------------

## Create a directory
Make sure to create a directory wherever you keep your projects.
First, if you plan on contributing to PolicyBrain, then fork PolicyBrain and work off of that fork. If you do not plan to contribute, then you can clone the main repo.

Open a terminal window and run the following commands:
```
mkdir project_name
```

## Clone the repo in the new directory

```
git clone git@github.com:OpenSourcePolicyCenter/webapp-public.git
```

## Create a conda environment for your local development

Follow [these instructions in README_local_development.md](https://github.com/OpenSourcePolicyCenter/webapp-public/blob/master/README_local_development.md) for installing all the Python packages you'll need and installing the right versions of the open-source-economics packages.

Then make sure you have done:
```
source activate aei_dropq
```
before continuing the remaining instructions.

## Using foreman
Since Django can be a more involved process using foreman might be a better tool for some situations. If no work will be done on the back end, then foreman might be the tool of choice (although once Django is setup all you will have to do is run the server locally to make use of it.)

Some important points:
- You must start the virtual environment.
- The Heroku toolbar that is installed with the requirements.txt file is expecting PostgreSQL to exist on your system.

After the environment is activated the following command will start foreman:
```
foreman start
```
Once the server has started foreman will use port 5000.

## Building Static Files
To setup your environment for building static assets:
```bash
npm install
npm install -g bower
bower install
```

To compile LESS assets:
```bash
gulp less
```

Collect static files and make sure changes get committed back:
```bash
# swap out YOURUSERNAME with OpenSourcePolicyCenter if you did not fork this project and
# your user name if you did
git clone https://github.com/YOURUSERNAME/PolicyBrain.git
cd PolicyBrain
git remote add upstream https://github.com/OpenSourcePolicyCenter/PolicyBrain
pushd deploy
./install_taxbrain_server.sh
popd
source activate aei_dropq && source webapp_env.sh
python manage.py collectstatic
python manage.py migrate
python manage.py runserver
```

## Using Django
Once all the dependecies are installed a couple of commands are necessary to get the Django project up and running and onto ```./manage.py runserver```. Make sure the virtual environment is activated.

### First update the settings.py file located in the webapp dir (webapp/settings.py)
In the settings.py file there is a database configuration that looks like:

```
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'taxcalc',
'USER': 'postgres',
'PASSWORD': '',
'HOST': '',
'PORT': '5432',
}
}
```
1) Change the USER to your user name (the one you used to setup Postgres).
2) Change the PASSWORD to the password you used to setup Postgres.
3) Change HOST to 127.0.0.1

### Using SQLite as an alternative to Postgres
Your environment settings file should include a variable named `DATABASE_URL`. If you would rather use SQLite than Postgres for your development, simply comment out or delete this line. The application will default to using SQLite as your database.

# PLEASE DO NOT COMMIT YOUR LOCAL CHANGES TO THE DATABASE CONFIG IN THE SETTINGS FILE. GIT STASH THEM!
## ALTERNATIVELY, STOP TRACKING LOCAL CHANGES TO THIS FILE WITH:
## `git update-index --assume-unchanged webapp/settings.py`

Next change the DEBUG & TEMPLATE_DEBUG settings to True.

### Second migrations have to been run. Migrations manage the schema for all database objects. Go to the root of the project simply run:
```
./manage.py migrate
Now, the Django app should be up and running. You can access the local instance of https://www.ospc.org/ at http://localhost:8000. Next, set up Redis, Flask, and Celery. This step allows you to submit and run jobs.
In another terminal, run the following commands
```
Django will then run the migrations and all the tables will be created in the db. NOTE: it is critical that migrations are run when updating models, otherwise the changes to the models will not be recognized and errors will be thrown by Django (these errors tend to be increasingly informative and you will usually be prompted by Django that there are unmigrated changes when you run the local server.)
# Go to the PolicyBrain directory
cd PolicyBrain/
source activate aei_dropq && source webapp_env.sh
cd deploy/taxbrain_server

### Third, it's time run the server. Simply run:
```
./manage.py runserver
```
# ignore the following block if you do not have access to the taxpuf package
conda config --add channels 'https://conda.anaconda.org/t/YOUR_TOKEN_HERE/opensourcepolicycenter'
conda install taxpuf
write-latest-taxpuf
gunzip -c puf.csv.gz > puf.csv

supervisord -c supervisord_local.conf

Now you have a live project being run locally at least for the front end Django app. You'll be able to see the pages and forms of ospc.org on http://localhost:8000 but you won't be able to submit and run jobs without error unless you follow the instructions below for starting flask, celery and redis.

### Fourth, run celery:
In another separate terminal tab or window:
```
taxbrain-celery-worker
```
### Fifth, run flask:
In another separate terminal tab or window:
```
taxbrain-flask-worker
```
### Sixth, run redis
In another separate terminal tab or window:
```
redis-server
```
### Seventh, if you edit your code...

If you edit your code or reinstall any part of the code, including even javascript assets, then you must to Ctrl+C to kill and restart each of the following processes:
* The `runserver` process
* The `taxbrain-celery-worker` process
* The `taxbrain-flask-worker` process