localvir.md

Local Development Setup

The instructions on this page will guide you in setting up a local development environment in your system. First things first, BadgeYay needs 'Python 3' to run. Most of the distros come bundled with that but if it is not there please install it first. We will be installing postgres, but be sure you have libxml2, zlib, and jpeg. (Most distros do have them)

These are some additional depencies that you will need:

$ sudo apt-get update

Video Installation

Steps

Make sure you have the dependencies mentioned above installed before proceeding further.

• Step 0 - For a start, fork BadgeYay to your own github account. Then, clone it to your local system. You will need to cd into your local badgeyay directory.

• Step 1

$ git clone -b development https://github.com/<your_username>/badgeyay.git
$ cd badgeyay

Add an upstream remote so that you can push your patched branches for starting a PR .

$ cd badgeyay
$ git remote add upstream https://github.com/fossasia/badgeyay.git

• Step 2 - Install the python requirements. You need to be present in the root directory of the project.

  • System Wide Installation

  sudo -H pip3 install -r backend/requirements.txt

  Note: Errors might result here, just see which package is unmet, and just install them using the distro's package manager. You may need to upgrade your pip version

  • Installation in Virtual Environment

  It is recommended that you use virtualenv and virtualenvwrapper to maintain a clean Python 3 environment. Create a virtualenv:

  $ source `which virtualenvwrapper.sh`
  $ mkvirtualenv -p python3 badgeyay
  (badgeyay) $ deactivate         # To deactivate the virtual environment
  $ workon badgeyay               # To activate it again

  OR

  $ sudo apt-get install python3-venv
  $ python3 -m venv badgeyay
  $ source badgeyay/bin/activate

  source 'which virtualenvwrapper.sh' is used to prevent from breaking the 'mkvirtualenv' command, you can find more about the issue, here.

  • Now, since you are inside a virtual environment, you can setup 'badgeyay' as an editable package.
  • Install all the requirements.

  (badgeyay)$ pip3 install -r backend/requirements.txt

• Postgres Installation

$ sudo apt-get install postgresql postgresql-contrib libssl-dev

For MacOS

brew install postgresql

• Step 3 - Create the database. For that we first open the psql shell. Go to the directory where your postgres file is stored.

# For linux users
$ sudo -u postgres psql

# For MacOS users
psql -d postgres

While inside psql, create a user for badgeyay and then using the user create the database.

For ease of development, you should create Postgres user with the same username as your OS account. For example, if your OS login account is tom, then you should create tom user in Postgres. By this, you can skip entering password when using database.

CREATE USER tom WITH PASSWORD 'start';
CREATE DATABASE badgeyay WITH OWNER tom;

Once database is created, exit the psql shell with \q followed by ENTER. Note that the password above was start and the user name was tom

If you want a graphical interface for this, you can try pgAdmin.

• Step 4 - Copy the .env.example and rename it to .env (create an .env file or setup the .env file similar to .env.example file

According to the name of the user and its password that you have created, you will need to set the credentials in the .env file.

• By default, the user and password is 'postgres'. So if you make the user with the same credentials, there is no need to set these variables. When inside psql, create a user 'postgres' for badgeyay and then using the user create the database.

In the .env file, set the BADGEYAY_ENV variable to LOCAL

BADGEYAY_ENV = 'LOCAL'

Add the FIREBASE_DB_URL, FIREBASE_STORAGE_BUCKET as it is from .env.example to .env

• Step 5 - Start the postgresql service

You need to have postgresql running in the background.

sudo service postgresql restart

For Mac Users:

brew services restart postgresql

• Step 6 - Start the application

• To run the project on a local machine (default mode).

First run the ember server as given here. It is necessary to run both the ember server and as well as the python backend server to get the service up and running.

Then, in a terminal, type

(badgeyay/backend) $ export FLASK_APP=run.py
(badgeyay/backend)$ flask run

• To run the project on a local machine (debug mode).

(badgeyay/backend) $ export FLASK_DEBUG=1
(badgeyay/backend)$ flask run

If Flask Run does not work on Mac Try using :

python3 -m flask run

Important Notes

• For MacOS Users:
  • If during executing Step-2, You can get some build error during Pillow Cycle, Please follow this commands :

  brew install libjpeg zlib
  brew link zlib --force
  xcode-select --install
  sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /

  • If you get lcrypto missing libraries error during the installation process, Please follow this :

  brew reinstall openssl
  export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/opt/openssl/lib/

Preferred Development Workflow

1. Activate the virtual environment.

$ workon badgeyay # To activate it again
(badgeyay) $

2. Get the latest copy of code from upstream.

(badgeyay) $ git pull upstream development

3. Once you get assigned an issue, create a new branch from 'development'.

(badgeyay) $ git checkout -b XXX-mock-issue # XXX is the issue number

4. Work on your patch, test it and when it's done, push it to your fork.

(badgeyay) $ git push origin XXX-mock-issue

5. File a PR and wait for the maintainers to suggest reviews or in the best case merge the PR. Then just update 'development' of your local clone.

(badgeyay) $ git pull upstream master

And then loop back again. For contribution guidelines, refer here