From 00ce5302a1552b30417edffc31422a4e7f78fc82 Mon Sep 17 00:00:00 2001 From: K mehant Date: Sun, 20 Oct 2019 18:25:38 +0530 Subject: [PATCH] Make documentation concise --- README.md | 338 +++--------------------------------------------------- 1 file changed, 17 insertions(+), 321 deletions(-) diff --git a/README.md b/README.md index c3675d3b..cee15ac7 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,10 @@ Automated Download Queue for Enterprise to take the best use of Internet bandwid
-# About +## About Bassa solves the problem of wasting internet bandwidth by queuing a download if it is larger than a given threshold value in high traffic and when the traffic is low, it completes the download of the files. After the files are downloaded, the users can get their files from the local servers which do not require external internet bandwidth. -### Main functionalities +## Main functionalities * Provides an interface for users to add their downloads as links or torrent magnet links * Provide users with an interface to view and download the files in the local server * Provide a rating system for users to rate the files residing in local server @@ -30,346 +30,42 @@ Bassa solves the problem of wasting internet bandwidth by queuing a download if * Mark inappropriate downloads * Provides admins with an interface to deal with inappropriate files -### Architecture - -Bassa is a multi-tier application which can serve users through dedicated Web, Android and iOS clients. - -
- -![Bassa Architecture](https://b.imge.to/2019/07/28/kNdAC.png) - -
- -**Components** -* Bassa API server is implemented as a [flask-socketio](https://flask-socketio.readthedocs.io/en/latest/) server written in Python. -* Bassa web client is implemented using Angular written in JavaScript. (*Moving to create-react-app very soon*) -* Bassa [Android and iOS mobile clients](https://github.com/scorelab/Bassa-mobile) are implemented using react native written in JavaScript. -* Bassa uses MySQL 5.X as database server. -* Bassa uses [Aria2c RPC server](https://aria2.github.io/) to download files. -* Bassa can be used with [Minio](https://github.com/minio/minio) file storage server as a file system and also for storing files to Amazon S3 cloud storage. -
- -# Getting Started ## Installation Guide -### Setting up Bassa using Docker and docker-compose [Recommended] -In order to setup Bassa using docker, install the latest version of [docker](https://docs.docker.com/install/) with [docker-compose tool](https://docs.docker.com/compose/install/) on your machine. -Clone the [Bassa GitHub repository](https://github.com/scorelab/Bassa). -Run the below command to move into the root folder. -``` -cd Bassa -``` -We will be using docker-compose tool to build images and finally spin up all our containers and then we can start using Bassa. *docker-compose configuration file* has configuration for each container and you are free to modify it. You can run the below command.
- -For development: -```bash -docker-compose -f docker-compose.dev.yml up --build -``` -You can access the Bassa Web Client at port **3000** served by Gulp.
-For production: -```bash -docker-compose up --build -``` -You can access the Bassa Web Client at port **80** served by Nginx.
-You can run a specific container using docker-compose tool. You can do that using the service names. - -| Service | Service Name | -|----------|:-------------:| -| API server | api | -| Web client | web | -| Database server | db | -| Aria2c | aria2c | - -**Usage** -```bash -docker-compose build [SERVICE NAME] -docker-compose run [SERVICE NAME] -``` - -### Setting up Bassa from the source code -In order to to setup Bassa from the source code, you need a machine with either Linux, MacOS or Windows operating system. -Keep an eye on the configuration files such as dl.conf as they are specific to docker environment. - -### Setting up Bassa on Linux based operating systems - -First clone and move to the project repository - -``` -git clone https://github.com/scorelab/Bassa.git && cd Bassa -``` - -Install Bassa dependencies. -``` -sudo ./setup.sh -``` - -#### Setting up Aria2c RPC server - -Open a new terminal window, move to downloads folder and start Aria2c server. -``` -cd downloads/ -aria2c --enable-rpc --rpc-listen-all -``` - -#### Setting up Bassa Database - -Start the MySQL service on your machine and open the MySQL terminal to type the command for creating the Bassa Database. -``` -create database Bassa; -``` -Exit from MySQL terminal and insert the Bassa database schema in to the created database. -``` -cd db_schema/ -mysql -u root -p Bassa < Bassa.sql -``` -Configure the Bassa database credentials in *components/core/DBCon.py* database connector file. - -If the environment variables are being used, modify as following : -```python -_db=MySQLdb.connect("db", os.environ.get('YOUR_DB_USERNAME'), os.environ.get('YOUR_DB_PASSWORD'), os.environ.get('Bassa')) -``` - -If the environment variables are not configured and hardcoded strings are being used, replace as : -```python -_db=MySQLdb.connect(host="localhost", user="YOUR_DB_USERNAME", passwd="YOUR_DB_PASSWORD",db= "Bassa") -``` -#### Setting up Bassa API server - -Change directory to API code base and install python modules -``` -cd components/core/ -sudo python3 setup.py develop -``` -Start Bassa API server -``` -sudo python3 Main.py -``` -#### Setting up Bassa Web client and Gulp - -Open a new terminal window, move to UI code base and install node modules. -```bash -cd ui/ -sudo npm install -sudo npm install --global bower gulp-cli -``` -Start the Bassa Web Client -```bash -gulp serve -``` -You can access the Bassa Web Client at port **3000**. - - -### Setting up Bassa on MacOS - -First clone and move to the project repository - -``` -git clone https://github.com/scorelab/Bassa.git && cd Bassa -``` - -Install Bassa dependencies. -``` -sudo ./setup.sh -``` - -#### Setting up Aria2c RPC server - -Open a new terminal window, move to downloads folder and start Aria2c server. -``` -cd downloads/ -aria2c --enable-rpc --rpc-listen-all -``` - -#### Setting up Bassa Database +### Setting up Bassa via containers +* Using Docker and docker-compose [Recommended] [LINK](https://github.com/scorelab/Bassa/wiki/Setting-up-Bassa-via-containers) +* Using Podman, buildah and podman-compose [Recommended] [LINK]() -Start the MySQL service on your machine and open the MySQL terminal to type the command for creating the Bassa Database. -``` -create database Bassa; -``` -Exit from MySQL terminal and insert the Bassa database schema in to the created database. -``` -cd db_schema/ -mysql -u root -p Bassa < Bassa.sql -``` -Configure the Bassa database credentials in *components/core/DBCon.py* database connector file. +### Setting up Bassa on host from source code +* On Linux based operating systems [LINK](https://github.com/scorelab/Bassa/wiki/Linux-Installation-Guide) +* On MacOS [LINK](https://github.com/scorelab/Bassa/wiki/MacOS-Installation-Guide) +* On Windows operation system [LINK](https://github.com/scorelab/Bassa/wiki/Windows-Installation-Guide) -If the environment variables are being used, modify as following : -```python -_db=MySQLdb.connect("db", os.environ.get('YOUR_DB_USERNAME'), os.environ.get('YOUR_DB_PASSWORD'), os.environ.get('Bassa')) -``` -If the environment variables are not configured and hardcoded strings are being used, replace as : -```python -_db=MySQLdb.connect(host="localhost", user="YOUR_DB_USERNAME", passwd="YOUR_DB_PASSWORD",db= "Bassa") -``` -#### Setting up Bassa API server +## User Guide +You can learn how to use Bassa as an effective download queue for communities by taking best use of internet bandwidth. You can know about different functionalities according to the roles provided. Please move to this [User Guide](https://github.com/scorelab/Bassa/wiki/How-to-use-Bassa) -Change directory to API code base and install python modules -``` -cd components/core/ -sudo python3 setup.py develop -``` -Start Bassa API server -``` -sudo python3 Main.py -``` -#### Setting up Bassa Web client and Gulp +## Developer Guide +Once you have setup Bassa locally, you can move to our [Developer Guide](https://github.com/scorelab/Bassa/wiki/Bassa:-Developer-Guide) to know more about the project internals. -Open a new terminal window, move to UI code base and install node modules. -```bash -cd ui/ -sudo npm install -sudo npm install --global bower gulp-cli -``` -Start the Bassa Web Client -```bash -gulp serve -``` -You can access the Bassa Web Client at port **3000**. - -### Setting up Bassa on Windows operating system - -First clone and move to the project repository - -``` -git clone https://github.com/scorelab/Bassa.git && cd Bassa -``` - -Install latest [python3](https://www.python.org/downloads/release/python-363/) on your machine. \ -Install latest version of [Aria2](https://aria2.github.io/) and add the executable to the [PATH variable]( https://msdn.microsoft.com/en-us/library/office/ee537574(v=office.14).aspx). \ -Install the [MySQl Server](https://dev.mysql.com/downloads/installer/) and make sure to check MySQL component and C connectors during installation. \ -Install [Node](https://nodejs.org/en/) on your windows machine.\ - -#### Setting up Aria2c RPC server - -Open a new CMD window, move to downloads folder and start Aria2c server. -``` -cd downloads/ -aria2c --enable-rpc --rpc-listen-all -``` - -#### Setting up Bassa Database - -Open the MySQL command line client to type the command for creating the Bassa Database. -``` -create database Bassa; -``` -Exit from MySQL client and insert the Bassa database schema in to the created database. -``` -cd db_schema/ -mysql -u root -p Bassa < Bassa.sql -``` -Configure the Bassa database credentials in *components/core/DBCon.py* database connector file. - -If the environment variables are being used, modify as following : -```python -_db=MySQLdb.connect("db", os.environ.get('YOUR_DB_USERNAME'), os.environ.get('YOUR_DB_PASSWORD'), os.environ.get('Bassa')) -``` - -If the environment variables are not configured and hardcoded strings are being used, replace as : -```python -_db=MySQLdb.connect(host="localhost", user="YOUR_DB_USERNAME", passwd="YOUR_DB_PASSWORD",db= "Bassa") -``` -#### Setting up Bassa API server - -Change directory to API code base and install python modules -``` -cd components/core/ -sudo python setup.py develop -``` -Start Bassa API server -``` -sudo python Main.py -``` -#### Setting up Bassa Web client and Gulp - -Open a new terminal window, move to UI code base and install node modules. -```bash -cd ui/ -sudo npm install -sudo npm install --global bower gulp-cli -``` -Start the Bassa Web Client -```bash -gulp serve -``` -You can access the Bassa Web Client at port **3000**. - -## Usage -Please use the mock-up username and password to try and develop Bassa. - -| Key | Value | -|----------|:-------------:| -| user_name | rand | -| password | pass | - -You can even refer to a Video tutorial on how to use Bassa, available on [Youtube](https://youtu.be/NxS8T1EphCA)

-Once developed, Bassa will save internet bandwidth by downloading files when the traffic is low. In the current build, you can log in either as a user or as an admin and add links for files to download. The admin can start the downloads as and when he/she likes or when he/she feels that the traffic on the network is low. After the download, the users can get their files from local servers which does not need internet bandwidth. - -#### If you’re a user -- If you’re a new user, you need to sign up first and can only login after the admin has approved your account. - -#### If you’re an admin -- Only an admin account can access the “Admin” tab in Bassa -- In the admin tab, you have three available processes-
- **a) Start/Kill downloads-** You can start the downloads queued at the time of your liking
- **b) Sign up Requests-** As an admin, you need to approve the accounts of all the new users before they can start using Bassa
- **c) Usage of top heaviest users-** You get access to a graph that shows the usage percentage of the heaviest users - -#### Common Functionalities -- Once logged in, navigate to the dashboard section. You can add a link to a file or a magnet link in the text field labeled “Add download*”. You can then see the link added under the “Ongoing downloads tab”
-- After the admin has approved the download, your file begins to download. It gets saved on the local servers from which you can get your files without the use of external bandwidth
-- In the “Completed” section, you can view all the details of downloads that Bassa has completed till now - -Bassa is an essential tool for managing downloads and to make the best use of Internet Bandwidth. It is also compatible with Amazon cloud storage. - -## Running Tests - -### API Tests -* Make sure the python server is working and you have an open connection to the database. -* Open the python console in your terminal by running the command `python3`. -* In the console that opens, import the test files, like so: - -``` - from tests.Bassa_endpoint_test import * - from tests.login_test import * -``` - -### UI Tests - -``` -cd ui -npm test OR yarn test -``` - -## Troubleshooting -Incase if you are stuck up with any issues during the setup or usage, look in to the [troubleshooting](https://github.com/scorelab/Bassa/issues/375) list for help or file a new issue on the project repository. - -
- -# Communication +## Communication Feel free to discuss on our [Bassa gitter channel](https://gitter.im/scorelab/Bassa). You can also discuss about other projects on [SCoRe Lab gitter channel](https://gitter.im/scorelab/scorelab). -# Developers - -Please go through the developer guides in [Bassa wiki](https://github.com/scorelab/Bassa/wiki) - - -# Contributors +## Contributors This project exists thanks to all the people who contribute. -# Backers +## Backers Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/Bassa#backer)] -# Sponsors +## Sponsors Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/Bassa#sponsor)]