Open Source Programs (Backend)

Open Source Programs (OSP) is an application that simplifies the processing and selection procedure of Open Source Programs of AnitaB.org Open Source or other third-party programs. This is the Backend repo for OSP.

Tech Stack

• Django 3.0.7
• Django REST Framework 3.11.0
• Python 3.7+

API Documentation

• Postman Docs

Setup

To setup the project locally go through this wiki page. Make sure you have installed the following:

• pip
• virtualenv
• PostgreSQL

Next follow these instructions.

1. Database Setup: Before starting with the project create a db in you local using PostgreSQL with the following details. Refer to main/settings.py if you have any confusion.

   NAME: osp
   USER: osp
   PASSWORD: osp
   HOST: localhost
   

   You may run the following commands for local setup of DB in Linux:

   cd anitab-forms-backend
   sudo -i -u postgres
   createuser osp --pwprompt
   psql
   CREATE DATABASE osp;
   \c osp;
   GRANT ALL PRIVILEGES ON DATABASE osp to osp;
   

   You may run the following commands for local setup of DB in Windows:

   cd anitab-forms-backend
   psql -U postgres
   CREATE ROLE osp LOGIN PASSWORD 'osp' NOINHERIT CREATEDB;
   CREATE DATABASE osp;
   \c osp;
   GRANT ALL PRIVILEGES ON DATABASE osp to osp;
   

2. Set the environment variables: You need to download Zulip API key file from your user-settings on Zulip. The file you download is named as download or rename it to download. Place that download file in the project's directory. For more information follow Environment Variables section.

3. Move into the project's directory.

   cd anitab-forms-backend
   

4. Create virtual environment (this is not a hard requirement, but its advisable)

   virtualenv venv
   

   Activating virtual environment for Linux users:

   source venv/bin/activate
   

   Activating virtual environment for Git Bash users:

   source ./venv/Scripts/activate
   

   Activating virtual environment for Windows users:

   venv\Scripts\activate
   

5. To install dependencies:

   pip install -r requirements.txt
   

6. To run the migrations run:

   python manage.py migrate
   

7. To run the server:

   python manage.py runserver
   

8. Navigate to http://localhost:8000/ in your browser.

9. To change the port you may run python manage.py runserver <port_number>

10. To run the migrations run: python manage.py migrate

11. You can terminate the process by Ctrl+C in your terminal.

Follow the given instructions for Login into the app.

1. You can register a new user by making a POST request on /api/token_auth/register/. After this confirmation e-mail will be sent to standard output (terminal). To receive confirmation e-mail using Sendgrid see this. The content of the request must be like this:

   {
       "username":"< YOUR USERNAME >",
       "email":"< YOUR EMAIL >",
       "password":"< YOUR PASSWORD >",
       "confirm_password":"< YOUR PASSWORD >"  
   }

2. To create the superuser run:

   python manage.py createsuperuser
   

   Fill up the things it asked to and then Login into the app.

Environment Variables

1. Zulip API KEY file - You can go Zulip and follow these instructions to get your API KEY. Download the file and save it in the root folder of the project with the name download.

2. SENDGRID_API_KEY - It is optional for development. To use this variable make DEBUG=False in settings.py. Follow the given steps to create a Sendgrid API key:

   1. Go to Sendgrid's website
   2. Navigate to Settings on the left navigation bar, and then - select API Keys.
   3. Click Create API Key.
   4. Give your API key a name.
   5. Select Full Access, Restricted Access, or Billing Access. If you're selecting Restricted Access, or Billing Access, select the specific permissions to give each category. For more information, see API key permissions.
   6. Click Create & View.
   7. The API KEY is generated and displayed to you just once. So be sure to copy and save it somewhere.

Add it to your .env file as follows:

export SENDGRID_API_KEY=<your-sendgrid-api-key>

3. SECRET_KEY - This environment variable is required for running the backend. Add SECRET_KEY in .env file or export it by using export SECRET_KEY=<YOUR SECRET KEY>.

4. DB_BACKEND - This environment variable is used here to get the the backend class of the database. Different databases have different backends in django. You can read more about it here. Its default backend is postgresql.

5. DB_NAME - This environment variable is required to get the name of the database. By default, its value is osp.

6. DB_USERNAME - This environment variable is required to get the USERNAME of the user with all privileges to the above mentioned database.

7. DB_PASSWORD - This environment variable is required to get the password of the above mentioned user i.e. the user with all the privileges to the database.

8. DB_HOST - It is used to get the database host from the env variables. For docker it must be set to db otherwise its default value is localhost.

9. DB_PORT - It is used to get the database port from the env variables. Different database backends have different ports. Its default value is of postgresql port i.e. 5432.

Testing

To run the tests run: python manage.py test.

QA Checks

Before creating a pull-request, always run QA checks to make your code more readable and error-free. Steps to run QA checks are:

1. Install QA checks dependencies:

   pip install black==20.8b1
   pip install isort==5.7.0
   pip install flake8==3.8.4
   

2. Run QA checks: ./osp-qa-checks.

Run with Docker

1. Make sure the latest version of docker and docker-compose are installed.

• For docker run docker -v from your terminal. If docker is not installed, install it from here.
• For docker-compose run docker-compose -v from terminal. If it is not installed then install it by running pip install docker-compose or from here.

2. Change Database HOST in settings.py

• Go to main/settings.py
• Under databases change host to db.

3. Build docker image

Execute sudo docker-compose run web to build the image.

4. Run docker image

Run sudo docker-compose up from the root directory of project. Navigate to http://localhost:8000 in your browser.

Note

• Run docker-compose up --build to rebuild the image.
• To interact with docker containers use docker exec -it {container id} bash from your terminal. Container id can be found using docker ps.

Documentation

Documentation for the project is hosted here. Docusaurus has been used for maintaining the documentation of the project.

• Read the Meeting minutes notes from our open sessions about the project.
• For setting up the project locally watch this video.
• To learn about the project's initial features, watch the video of project demonstration.
• Design and Mocks Google Drive folder.
• Timeline deliverables for the project during GSoC 2020.
• GSoC 2020 Project Meeting Minutes [Old].

For more information, you can read backend project wiki and the web project wiki.

Contributing

Please read the Contributing guidelines, Code of Conduct and Reporting Guidelines

Contributors

Thanks goes to these people (emoji key):

Shipra Verma 🚧

Sankalp 🚧

Kesha K. Kaneria 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

Contact

You can reach the admins, maintainers and our community on AnitaB.org Open Source Zulip. If you are interested in contributing to the OSP project, you may join the stream #open-source-progs and ask questions or intereact with the community. Join Us!

License

Open Source Programs Backend is licensed under the GNU General Public License v3.0. To know more about it you can read the LICENSE.