development.md

Development

Development Setup

Prerequisites

• macOS
• PostgreSQL

  brew install postgresql

• Redis (make sure the server runs on default port - 6379)

  brew install redis
  redis-server

Installing

1. Install the pip package manager

   sudo easy_install pip

2. Install Pyenv with brew

   brew update
   brew install pyenv pyenv-virtualenv

3. Install Python 3.6.4 with Pyenv

   pyenv install 3.6.4

4. Create and activate virtualenv with Python 3.6.4

   pyenv virtualenv 3.6.4 v-3.6.4
   pyenv activate v-3.6.4

5. Install the dependencies

   pip install pipenv
   pipenv install

6. Create a PostgreSQL database

   createdb your_postgresql_database_name

7. In root directory of gello, create a .env file following the same format as .env.sample

   cp .env.sample .env

   Follow configuration guide to configure environment variables in .env

8. Run the database migrations

   python manage.py db upgrade

9. Run the deployment command to fetch API Data and create the admin user

   python manage.py deploy

10. In one terminal, start the worker

    pyenv activate v-3.6.4
    celery worker -A celery_worker.celery --loglevel=info

11. In another terminal, run the server

    pyenv activate v-3.6.4
    python run.py

12. Open http://localhost:5000/.

13. Log in with your admin credentials ADMIN_EMAIL and ADMIN_PASSWORD.

14. Complete the onboarding form.

Testing

Unit Tests

Unit tests may be run with:

python manage.py test

Gello will use the TEST_DATABASE_URL as the database when you run tests, so be sure to export it before running python manage.py test.

export TEST_DATABASE_URL='the_url_for_a_postgresql_database'

Integration Tests

1. Follow instructions to download and setup ngrok

2. Expose localhost (usually port 5000)

   ./ngrok http 5000

   You should see a line that looks similar to this:

   Forwarding    http://7e9ea9dc.ngrok.io -> 127.0.0.1:5000

3. Copy the url *.ngrok.io

   In views.py, replace the value of url_root with this url (temporarily for testing)

CreateGitHubWebhook.delay( url_root='http://7e9ea9dc.ngrok.io/', # request.url_root, repo_id=create_form.get_repo_id() ) ```

4. Now you can create new webhooks (through creating subscriptions) on Gello, and they would link to the ngrok url (which forwards to your localhost)

5. Don't forget to delete the test webhooks and change the line back when you're done!

Manual Testing

Flask comes with its own command line interface (CLI) which comes in handy for testing and debugging within the application context. To use the flask CLI, simply run the following command from Gello's root directory:

flask shell

If you're familiar with the IPython interface, you can run the flask CLI using IPython by installing a couple packages, then running the same command as above:

pip install ipython
pip install flask-shell-ipython
flask shell

From within the shell, you can access defined classes and call functions from within the application context. This is especially useful when you need to test and debug parts of the application that require database access. For example, you can check that your database models are working correctly by fetching, creating, and updating them from within the flask shell:

import app.models as models
from app import db
# Fetch all boards
boards = models.Board.query.all()
# Create a new board
new_board = Board(name="New Board", url="https://example.com", trello_board_id="EXAMPLE")
# Add the new board to the session
db.session.add(new_board)
# edit an existing board
boards[0].name = "new name"
# Persist these changes
db.session.commit()

Other possible applications of the flask CLI include testing API service calls and celery tasks with custom inputs.

Coverage Reports

Coverage reports may be generated with:

coverage run --source=app manage.py test
coverage report

Common Errors

Below are errors that you might encounter during local set-up and their solutions:

ZipImportError

zipimport.ZipImportError: can't decompress data; zlib not available

Run 'brew info zlib', and follow output instructions to set corresponding environment variables.

pyenv-virtualenv Initialization Error

Failed to activate virtualenv. Perhaps pyenv-virtualenv has not been loaded into your shell properly. Please restart current shell and try again.

Add the following to your bashrc file ( ~/.bashrc):

eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

GithubException

github.GithubException.RateLimitExceededException: 403 {'message': "API rate limit exceeded."}

Verify that the GITHUB_API_TOKEN and GITHUB_ORG_LOGIN are set up correctly in .env, and that environment variables are loaded properly.