From 74c75b54bb9ded5b753778d337169a5b1a9c952e Mon Sep 17 00:00:00 2001 From: Harsh Khandeparkar Date: Sat, 10 Jun 2023 19:54:32 +0530 Subject: [PATCH] Updated the docs (README) - Golang version * docs: updated README docs * docs: added oauth docs to README --- .env.template | 2 +- README.md | 184 ++++++++++++++++++++++++++++++++++---------------- 2 files changed, 125 insertions(+), 61 deletions(-) diff --git a/.env.template b/.env.template index 9113b98c..75291b23 100644 --- a/.env.template +++ b/.env.template @@ -1,4 +1,4 @@ -MODE= +DEV= JWT_SECRET_KEY= client_id= client_secret= diff --git a/README.md b/README.md index ac0faa0f..5ea2937e 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,132 @@ -## Directory Structure - -MVC Strucutre is being followed. - -`main.go`: Driver Code for all of backend. - -`models`: Database Models - -`controllers`: Various handlers for HTTP Requests - -`routes`: Definitions of Sub-routers - -`utils`: Middlewares and other files common to multiple functions - -`scripts`: Extra scripts (unrelated to the usual flow of the webapp) - -`docs`: Documentation - -## File Naming Convention - -- Separate file for each Model. - -- Controller functions to be grouped together by their routes. - -- Each Subroute has a separate file. - -In short, don't keep any surprises. Use groupings as per your discretion. - -## Dependencies - -``` -gorilla/mux -jinzhu/gorm -golang-jwt/jwt/v4 -``` - -Also uses `golanglint-ci` for linting code. - -## Building - -- Clone the repo and `cd` into it's directory. +# KWoC Backend +KWoC backend server written in Go. + +## Table of Contents +- [Development](#development) + - [Setting Up Locally](#setting-up-locally) + - [Building](#building) + - [File Naming Convention](#file-naming-convention) +- [Project Structure](#project-structure) + - [File Structure](#file-structure) + - [Endpoints](#endpoints) + - [Environment Variables](#environment-variables) + - [Github OAuth](#github-oauth) + +## Development +### Setting Up Locally +- Install [Go](https://go.dev). +- Clone this repository. +- Run `go get` in the repository to download all the dependencies. +- Create a `.env` file to store all the [environment variables](#environment-variables). +- Set the `DEV` environment variable to `true`. This makes the server use a local sqlite3 database, `devDB.db`. +- Optionally set up [Github OAuth](#github-oauth) to test the log in endpoints. (See also: [Endpoints](#endpoints)) +- Run `go run .` to start the server. +- Optionally install [SQLiteStudio](https://sqlitestudio.pl/) or any similar tool to help manage the local sqlite3 database file `devDB.db`. +- Optionally install a tool such as [Postman](https://www.postman.com) to test the REST API. + +### File Naming Convention +See also: [File Structure](#file-structure). + +- Create a separate file for each model in `models/`. +- Group the controller functions by their routes. +- Create a separate file for each subroute. + +### Building +- Clone the repo and `cd` into its directory. - Run the following commands ```sh docker-compose build - docker-compose up + docker-compose up ``` -**NOTE**: If you face the following issue with `docker-compose`. +**NOTE**: If you face the following issue with `docker-compose`. > strconv.Atoi: parsing "": invalid syntax -This is because `docker-compose` is creating arbitrary container not in _docker-compose.yml_ and terminating the starting process.
+This is because `docker-compose` is creating an arbitrary container not in _docker-compose.yml_ and terminating the starting process.
**FIX**: Use `docker-compose-v1` instead of `docker-compose`. - +## Project Structure +### File Structure +This project follows the MVC Structure. +- `main.go`: The main file that is executed. +- `models/`: Database models. +- `controllers/`: Various handlers for HTTP requests. +- `routes/`: Definitions of sub-routers. +- `utils/`: Middlewares and other common utility functions. +- `scripts/`: Extra scripts (unrelated to the usual flow of the web app). +- `docs/`: Documentation. + +### Endpoints +The API exposes the following endpoints. (See also: [File Structure](#file-structure)) + +#### Healthcheck +Files: `routes/healthcheck.go`, `controllers/healthcheck.go`. +- `/healthcheck`(GET): Responds with the server and database status. +- `/healthcheck/ping`(GET): Responds with "Pong!" if the request was successful. + +#### Mentor +Files: `routes/mentor.go`, `controllers/mentor.go`. +- `/mentor/form`(POST): Registers a mentor. The following parameters are required. + - `name`: The name of the mentor. + - `email`: The email address of the mentor. + - `username`: The Github username of the mentor. +- `/mentor/dashboard`(POST): Responds with the information to be displayed on the mentor's dashboard, including a list of projects. The following parameters are required. + - `username`: The Github username of the mentor. +- `/mentor/all`(POST): Responds with a list of all the mentors' names and usernames. + +#### OAuth +Files: `routes/oauth.go`, `controllers/UserOAuth.go`. +- `/oauth`(POST): Logs in a user via Github OAuth. (See [Github OAuth](#github-oauth)) + +#### Project +Files: `routes/project.go`, `controllers/project.go`. +- `/project`(GET): Responds with a list of all projects. +- `/project/add`(POST): Adds a new project to the database. See the file `controllers/project.go` for a list of parameters. +- `/project/details`(POST): Responds with the details of a project. The following parameters are required. + - `id`: The ID of the project in the database. +- `/project/update`(PUT): Updates the details of a project. See the file `controllers/project.go` for a list of parameters. + +#### Stats +Files: `routes/stats.go`, `controllers/stats-overall.go`, `controllers/stats-project.go`, `controllers/stats-student.go`. +- `/stats/overall`(GET): Responds with the overall statistics. +- `/stats/projects`(GET): Responds with a list of all projects' statistics. +- `/stats/students`(GET): Responds with a list of all students' statistics. +- `/stats/student/exists/{username}`(GET): Responds with "true" if statistics for the given student exist in the database and "false" otherwise. +- `/stats/student/{username}`(GET): Responds with the stats for the given student. +- `/stats/mentor/{username}`(GET): Responds with a list of the mentor's project stats. + +#### Student +Files: `routes/student.go`, `controllers/student.go`. +- `/student/form`(POST): Registers a student. The following parameters are required. + - `name`: The name of the student. + - `email`: The email address of the student. + - `college`: The institute the student studies at. + - `username`: The Github username of the student. +- `/student/dashboard`(POST): Responds with the information to be displayed on the student's dashboard. The following parameters are required. + - `username`: The Github username of the student. +- `/student/bloglink`(POST): Adds a link to the student's blog to the database. The following parameters are required. + - `username`: The Github username of the student. + - `bloglink`: A link to the student's blog. + +### Environment Variables +Environment variables can be set using a .env file (see the `.env.template` file). The following variables are used. +- `DEV`: When set to `true`, uses a local sqlite3 database from a file `devDB.db`. +- `DATABASE_USERNAME`: The username used to log into the database. (Valid when `DEV` is not set to `true`) +- `DATABASE_PASSWORD`: The password used to log into the database. (valid when `DEV` is not set to `true`) +- `DATABASE_NAME`: The name of the database to log into. (Valid when `DEV` is not set to `true`) +- `DATABASE_HOST`: The host/url used to log into the database. (Valid when `DEV` is not set to `true`) +- `DATABASE_PORT`: The port used to log into the database. (Valid when `DEV` is not set to `true`) +- `client_id`: The client id used for Github OAuth. (See [Github OAuth](#github-oauth)) +- `client_secret`: The client secret used for Github OAuth. (See [Github OAuth](#github-oauth)) +- `JWT_SECRET_KEY`: The secret key used to create a JWT token. (It can be a randomly generated string) + +#### Github OAuth +KWoC uses Github [OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps#about-github-apps-and-oauth-apps) for log in authentication instead of passwords. + +To set up the KWoC server, a Github OAuth application has to be created and the client id and secret has to be set in the [environment variables](#environment-variables). + +- Follow [this](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) documentation to create an OAuth app. In the production server, use the `koss-service` account to create the application. +- Set the Homepage URL to `https://kwoc.kossiitkgp.org` and the authorization callback URL to `https://kwoc.kossiitkgp.org/oauth/` in the production application. +- Copy the client ID and the client secret (this should NEVER be made public) and set the `client_id` and `client_secret` [environment variables](#environment-variables) to these values. + +**** +> Please update this documentation if you make changes to the KWoC backend or any other part of KWoC which affects the backend. Future humans will praise you. \ No newline at end of file