-
Notifications
You must be signed in to change notification settings - Fork 4
Developer Manual
Welcome to the Developer Manual of the OSCHub.
- Developers
- Technical Team of the Community
- Setting up Local Environment
- Files and Scripts
- Google Sheets and OSCHub
- Testing Sheets API
- Google OAuth Login
- Adding a SuperUser
- Attendance Calculation
- Testing Out Events
- Further Developments
Follow the Developer manual in order to develop the project on your own, and recommend that you contact the Tech Leads of the Club, or the Maintainers of the project when you need assistance.
The manual acts as reference material, and as such, please ensure that you go through the manual before attempting to contact the maintainers.
Enjoy developing this project further!
In order to work on developing this project, you will be required to set up the Local Environment, for initial testing.
Let us start by setting up your Local environment.
-
Clone the project using
git clone https://github.com/Open-Source-Community-VIT-AP/oschub.gitcommand.If you face any issues, then please follow this link to know more about cloning git repositories.
There is a fair chance that you do not have access to clone the project, and in that case you might need to contact the Tech Leads of the club to grant you the necessary permissions.
Once your cloning is successful, please navigate to the oschub folder.
-
Before going further, you will need a
.envfile (containing the secrets of the application) which can be obtained by requesting the maintainers, if you wish to contribute to this project, for the Open Source Community at VIT AP.
You will not be requiring the.envfile, if you are basing your project off this repository.If you want to develop this project for personal or other use then we suggest you to make an
.envfile by referring the.env.example.
You will need a Google Cloud Platform account, PostgreSQL database and a Google Account, if you are making a environment key file on your own, further information about the.envfile will be updated soon.
Make sure that the file name is .env.
Now we need to install dependencies or packages that are necessary to run this project, onto your machine.
- To work on this project you will need python 3, and if you don’t have python installed on your personal computer then checkout the python installation.
-
Next, open your preferred terminal and navigate to the directory where the oschub project is located.
Following are some tips on navigating through files using your terminal.
-
We suggest you to make a python virtual environment next, as it gets easy to manage the installed packages without affecting your global python environment.
Follow venv - Python Documentation to set up your own virtual environment for this project.
Once done with the setup, please make sure to activate your python virtual environment. -
Now to install the packages run the
python -m pip install -r requirements.txtcommand on your terminal.To know more about this process, you can refer: Installing python packages using requirements.txt.
We are finally done with setting up the Dependencies.
Migrations are used to apply the changes we made on the Django Models to the Database Schema.
In simple terms, the database is not yet made or updated on your machine and without the Database you cannot proceed.
So, to continue we need you to make or update the database.
To know more about Migrations, checkout Django Migrations.
Let’s get started with the Django Migration process.
-
Comment out all the scripts that use this specific table.
i.e. Comment all the lines in:
\oschub\SheetMe.py
\oschub\accounts\admin.py
\oschub\dashboard\admin.py
\oschub\eventreg\admin.py
-
Now, run the following command on your terminal.
python manage.py migrate
this command will create/update the database and converts the changes to Database Schema.
-
Next, run the following command to generate a Database file.
python manage.py makemigrations
this command will apply the updated Schema to the Database.
-
Uncomment all the scripts which you had previously commented out.
i.e. Uncomment all the lines in:
\oschub\SheetMe.py
\oschub\accounts\admin.py
\oschub\dashboard\admin.py
\oschub\eventreg\admin.py
Now, all you need to do is to make sure that everything is working fine and in order to do so, you need to run the server on your local machine.
Try opening the server on a browser to view the project. We will fill you in on more details in the following section.
Running the server is really easy and a straightforward task.
-
Run the following command in your terminal which we opened in the last section…
python manage.py runserver
This command will start the server, first it checks all the settings and applications added to the project and runs a local server which you can open in your browser.
Once the server starts, you will be able to see either a URL or some errors.
If you face any error output then either you messed up some step before or it might be due to some other issue.
The proper fix for the error could be possible if you provide the log (you can also copy paste the error from your terminal).
So, feel free to create an Issue in the repository (Know more about creating Issues in Github: Mastering Issues - GitHub Guides). -
Executing this command will run a local server on your machine as host and you will be able to see a link on your terminal. The localhost URL will mostly look like this:
http://127.0.0.1:8000/
But it might differ for some machines.
Open the URL in your browser and you should be able to see the main page of the OSCHub.
By the way, if you wish to stop the server then press Ctrl + C and for Mac users it should be Cmd + C.
Kudos mate, you are done with setup and now it’s your turn to start developing this project.
Well, next up is checking out the Admin Interface Panel, and understanding how things work.
We have a server, data and a database in our hands but, we now definitely need a place to manage all these things.
Django provides you with the Django Admin Interface panel to access and manage the database.
Checkout Admin Manual page to know more.
-
This section is included to let you know about the purpose of the files present in the project directory.
The main directory of the project is the folder "
oschub" which contains about 12 or more files and folders.
So whenever we mention "the main project directory", it means we are referring to theoschubfolder.Our main project directory contains these files and folders as per the latest version of the project.
08-05-2021 19:00 578 .env 08-05-2021 18:48 223 .env.example 08-05-2021 18:48 <DIR> .github 08-05-2021 18:48 2,416 .gitignore 08-05-2021 19:00 <DIR> accounts 08-05-2021 18:48 <DIR> assets 08-05-2021 18:48 2,303 credentials.json 08-05-2021 19:00 <DIR> dashboard 08-05-2021 19:00 <DIR> eventreg 08-05-2021 18:48 11,558 LICENSE 08-05-2021 18:48 647 manage.py 08-05-2021 18:52 <DIR> oschub 08-05-2021 18:48 2,136 PopulateMe.py 08-05-2021 18:48 40 Procfile 08-05-2021 18:48 579 README.md 08-05-2021 18:48 171 requirements.txt 08-05-2021 18:48 14 runtime.txt 08-05-2021 18:48 5,455 SheetMe.py 08-05-2021 18:48 <DIR> staticfiles 08-05-2021 18:48 <DIR> templates
You might not have the "
.env" file as it is only available to the maintainers and the technical team of the Open Source Community club of VIT-AP. But you can create your own.envfile by going through.env.examplefile and if you are a member of our campus then you can also request us the latest.envfile and depending on your request we will help you out with what we can do..env.example: This is a template file that contains the sample data that is present in the original .env file.The
.envfile contains the developer environment variables such as username and password for google auth account, exclusive configuration settings for Django including the developer key and some other hosting settings..github: A folder created by git and contains the Issue Templates. You won't be tampering this file in the future as it's development is restricted to the maintainers of the repository..gitignore: A file created by git and contains the files and folders that are meant to be excluded from the repository.accounts: A django application, a directory that contains necessary all the python scripts to handle user accounts, mailing list and more.assets: A directory to store all the repository assets such as images, gifs and other files that will contribute to the look of the repository.credentials.json: A json file that contains the required data to enable Google Sheets API. I won't recommend you to touch this file 😅.dashboard: A django application, a directory that contains all the necessary python scripts to handle dashboard views, events and more.eventreg: Another django application, a directory that contains all the necessary python scripts to handle event registration, event handling, "attendance" and more.LICENSE: A file created by github which specifies the current license that the project is using.manage.py: A python script created by django. It is used by developers to execute and configure django shell commands. To know more aboutmanage.pycheckout - Django Admin and Manage.pyoschub: The django project directory that contains python scripts that are capable of setting up the main configuration and hosting settings.PopulateMe.py: A python script that is used for testing the database capability and data population with google sheets. More about this file will be described in Population Test section of Developer Manual.Procfile: A log file for the hosted server. Again, this file does not need any development so avoid tampering it.README.md: The main README file of the OSCHUB repository.requirements.txt: A text file that contains all the required python packages to run this project.runtime.txt: A text file that defines the python version on which the project was built. This file directs the online server to use the given python version to run this project.SheetMe.py: A python script that is fully responsible for uploading the event data to the Google Sheets. And yes, by event data we meant your attendance for different events. More about this file will be described in Google Sheets and OSCHUB section of Developer Manual.staticfiles: A directory that holds all the static files such as images, css scripts and js files for every django applications that are used by this project.templates: This folder consists the modified webpage templates. This directory lets django know that there are some changes made to the auto-generated django webpages and renders these webpages instead of the auto-generated webpages.
We hope that this section was enough to let you understand the file directories and scripts that are used in this project.
-
As the club generally works with Google Sheets as it's record keeping mechanism, we did not wish to alter the general practice and instead just made it easier for the Organizers to work with Google Sheets more efficiently.
Keeping this in mind, we now send the stored data in the database to Google Sheets, and this is done on the single click of a button.
This way, the organizers need not worry about manually entering data. -
We used the gspread package to handle the Google Sheets API requests.
The event-user registration data is present in the database of this project and theSheetMe.pyscript contains the method to process the data, find out which events are over and retrieves the data of those events from the database.
Finally, it sends a batch upload request using gspread and shares the data to the email IDs present in themail-listdatabase.The script doesn't make a new google sheet for every new event. Instead, it creates another sheet in a pre-defined spreadsheet, which will be renamed to the event name so that the admins can identify the updated data and know that this particular sheet contains the data of event
x.There is a lot more room for updates and improvements such as sorting out the sheets, documentation updates, and unit testing.
We encourage you to contribute to the repository with what you think might be a good addition.
Keep in mind, that the feature needs to be approved by the maintainers, however. -
Nope, we didn't cram a book 😂, instead we read the official documentation of GSheets API.
-
The initial stages of development utilized the Gsheets API, however, the data that was being sent was being done record by record, and we were pulling in quite a number of requests being sent.
This grew out to be quite expensive, as the Google Sheets API accepts only a limited number of requests that can be sent per project and time.So, we found the perfect alternative and it was Gspread package.
The package includes a method that lets the script to send batch update that may contain more rows but altogether the total request will be considered as 1. -
Even though we are using Gspread package, we are indirectly using the official GSheets API and to use the API we must configure an account and other things.
To know more simply refer theprerequisites sectionof this webpage
In the case that you need further details on this then checkout the official documentation of Gspread and GSheets API.
Feel free to checkout the SheetMe.py script to know how we implemented the backend.
Don't worry, we do have some comments to let you understand the purpose of the code.
-
Even though we have all the features, we cannot simply deploy it for production level as every software needs to be tested several times to debug the application.
To test this project we were required to have a large user base and enough event data to test the efficiency of the database, and also to test the Google Sheets integration. -
Well, we created a script to add tons of fake data to the database.
It was only possible with the help of the Faker Package.
We wrote a script to create realistic fake user data including our campus registration number and email IDs.You can know more about the implementation by referring the
PopulateMe.pyscript.The script works by adding the inputted number (eg: 1000 or more) of user data to the events that are not over yet.
In order to test the Database with this script, you need to first create one or more events that are set as ongoing and you need to run this script to add fake user data.Note: This script takes nearly 2 mins to 5 mins to generate 5000 rows of fake user data. -
The current version of
PopulateMe.pyonly supports generating fake user data such as name, email, reg id, attendance.
We need the script to also generate fake events and speakers. However, the script doesn't need any immediate development on this issue.
This section covers all about the login feature offered by OSCHub.
As mentioned before, we didn't want the user to go through the hassle of making a new login account, and keeping a track of the account.
So, we made OSCHub in such a way that you can login with your university email-id and that makes validation easier too.
It is not impossible to write a new Django application to handle the Google OAuth login but to save time, we utilized a package that lets you add OAuth features to your Django project.
It also supports numerous exisiting accounts such as Google, Facebook, Github, et cetera.
For this project, we chose only Google auth login as our official university communications are done using Gmail.
-
To integrate OAuth features, we used django-allauth package.
It is a simple Django third-party application, but before using it, we are required to configure some settings to support the Google Auth Login.Refer User Registration with Google OAuth and Django-AllAuth to know how we implemented this feature.
Note: You will be required to manually add some configuration settings to the database rows for AllAuth and you will get errors if you don't comment out the files we did before to prevent any database errors.
Before making any changes to the database, please make sure to comment out the files that use the database tables.
To implement this feature you will need a google account.
Everything is already mentioned in the above webpage link.
Note: This topic has been already covered in Admin Manual.
-
A superuser account is an account which gives the account holder the power to modify and view the database and more.
You can relate a SuperUser account to an Administrative account. This account is used by admin and staff to handle the site and databases, developers are given superuser accounts to test out new features which would require them to handle the database and backend. -
As introduced previously, Django provides you with its own Admin Interface.
The Django admin panel is a page where only developers and admins who have access to the server can login and manage data.
Firstly, you need to make a super account to access the Panel and once you are done with that, you will be able to log into it.The home page of the Django Admin Interface consists of all the databases and it's CRUD operations.
Apart from that, you can even customize the Admin Interface. To know more about customizing Django Admin Interface click here. -
To setup a new Super User account or Staff account, you need to follow the steps given below:
Creating a New Super user account would mean that the new superuser account data will be added to the database and you cannot update the table when the backend script requires access to the database files.
So, we need to comment and uncomment files again like we did for migration.
-
Comment out all the scripts that use this specific table.
i.e. Comment all the lines in:
\oschub\SheetMe.py
\oschub\accounts\admin.py
\oschub\dashboard\admin.py
\oschub\eventreg\admin.py
-
Now, run the following command on your terminal.
python manage.py createsuperuser
this command will create a new Super user account and follow the user input steps...
-
Uncomment all the scripts which you had previously commented out.
i.e. Uncomment all the lines in:
\oschub\SheetMe.py
\oschub\accounts\admin.py
\oschub\dashboard\admin.py
\oschub\eventreg\admin.py
-
With this, you must have successfully created a superuser account for the project.
-
One of the main motives of OSCHub, was to make form filling and attendance calculation easy.
OSCHub allows for the club organisers to relax and calculates the attendance data for every student, based on the events that he/she has attended. -
As of right now, the attendance is calculated simply based on the number of events that the student has attended.
This calculation can definitely be improved by adding in weightage for particular events, and determining as to whether or not the student has completed the minimum credits required for the club activities.For now, OSCHub will remember the events you had registered and attended from now on and you can view your attendance status by checking out the profile page on dashboard. More about this can also be found in
Attendance and other detailssection inUser Manual. -
As soon as a new Event is made, a student can register for the event.
Once the registered event starts, you will be able to notice an option to
check-inand to let us know that you have attended the event, you need to press the check-in button once then the user data will be stored in the database, and furthermore will be sent to the google spreadsheets when the event is over.
-
Try creating a new Event and Speaker in database, more about creating a new Event, a new Speaker and Handling the data with Google Sheets API are present in Admin Manual.
For any queries feel free to create an issue in this repository or ask in our official Discord Server.
- Presently, this project requires some optimizations and tweaks. But there is more room for new features and the possibility of finding a bug may not be zero, so you are always welcomed to give your ideas and opinions so that we can improve this project further.
We recommend that you read all of the documentation manuals available, so you understand the concept and the features that are provided by this project. This would be helpful in determining what the exact issue is, during the development of this project.
And hey, thank you for reading until the end of the Developer Manual!
Open Source Community, Vellore Institute of Technology AP.