-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated the docs (README) - Golang version
* docs: updated README docs * docs: added oauth docs to README
- Loading branch information
1 parent
417eb55
commit 74c75b5
Showing
2 changed files
with
125 additions
and
61 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| MODE= | ||
| DEV= | ||
| JWT_SECRET_KEY= | ||
| client_id= | ||
| client_secret= | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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.</br> | ||
| This is because `docker-compose` is creating an arbitrary container not in _docker-compose.yml_ and terminating the starting process.</br> | ||
| **FIX**: Use `docker-compose-v1` instead of `docker-compose`. | ||
|
|
||
| <!-- These are steps before the dockerfile was created, basically without it | ||
| - You can use the Makefile for automating the commands. Run `make help` for a list of commands. | ||
| - Currently, only two(subject to change) commands are supported - | ||
| * `make lint` - Run the lint checks | ||
| * `make build` - For building the codebase | ||
| - Run `go get` to install the dependencies | ||
| - Run `go run main.go` in the terminal | ||
| - Run `go build` to build into a single binary. | ||
| - Run `gofmt -s -w .` to lint all the files in one go. | ||
| --> | ||
| ## 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. |