291 lines
15 KiB
Markdown
291 lines
15 KiB
Markdown
# MIREA schedule by Winsomnia
|
|
|
|
[](https://dotnet.microsoft.com/download/dotnet/8.0)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
This project is a backend part of an application developed on ASP.NET , which provides an API for getting schedule data.
|
|
|
|
The main task is to provide convenient and flexible tools for accessing the schedule in various ways.
|
|
|
|
## Purpose
|
|
|
|
The purpose of this project is to provide convenient and flexible tools for obtaining schedule data.
|
|
|
|
In a situation where existing resources provide limited functionality or an inconvenient interface, this project aims to
|
|
provide users with a simple and effective tool for accessing information about class schedules.
|
|
|
|
Developing your own API and using your own tools for downloading and processing data allows you to ensure the
|
|
reliability, flexibility and extensibility of the application functionality.
|
|
|
|
## Features
|
|
|
|
1. **Flexible API**: The API provides a variety of methods for accessing schedule data. Unlike competitors that provide
|
|
a limited set of endpoints, this application provides a wider range of functionality, allowing you to get data about
|
|
groups, campuses, faculties, classrooms and teachers. You can get all the data at once or select specific IDs with
|
|
the details that are needed.
|
|
2. **Database Providers**: The application provides the capability of various database providers.
|
|
3. **Using self-written packages**: The project uses two proprietary NuGet packages. One of them is designed for parsing
|
|
schedules, and the other is for downloading Excel spreadsheets from external sites.
|
|
|
|
## Project status
|
|
|
|
The project is under development. Further development will be aimed at expanding the functionality and improving the
|
|
user experience.
|
|
|
|
# Environment Variables
|
|
|
|
This table provides information about the environment variables that are used in the application. These variables are
|
|
stored in the [.env](.env) file.
|
|
|
|
In addition to these variables, you also need to fill in a file with settings in json format. The web application
|
|
provided by this project already has everything necessary to configure the file in the Client-Server communication
|
|
format via the controller. If you need to get the configuration file otherwise, then you need to refer to the classes
|
|
that provide configuration-related variables.
|
|
|
|
Please note that the application will not work correctly if you do not fill in the required variables.
|
|
|
|
### General Configuration
|
|
|
|
| Variable | Default | Description | Required |
|
|
|------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
|
|
| PATH_TO_SAVE | ./ | The path to save the data. Saving logs, databases (if Sqlite), and other data that should be saved in a different place. REQUIRED if the application is inside the container. | ✔ |
|
|
| ACTUAL_SUB_PATH | | The actual sub path to the API. If the specified path ends with "/api", the system will avoid duplicating "api" in the final URL. | ❌ |
|
|
| SWAGGER_SUB_PATH | swagger | The sub path to the Swagger documentation. | ❌ |
|
|
| INTERNAL_PORT | 8080 | Specify the internal port on which the server will listen. | ❌ |
|
|
|
|
### Security Configuration
|
|
|
|
| Variable | Default | Description | Required |
|
|
|---------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------|----------|
|
|
| SECURITY_SIGNING_TOKEN | | JWT signature token. This token will be used to create and verify the signature of JWT tokens. Must be equal to 64 characters. | ✔ |
|
|
| SECURITY_ENCRYPTION_TOKEN | | Token for JWT encryption. This token will be used to encrypt and decrypt JWT tokens. Must be equal to 32 characters. | ✔ |
|
|
| SECURITY_LIFE_TIME_RT | 1440 | Time in minutes, which indicates after which time the Refresh Token will become invalid. | ❌ |
|
|
| SECURITY_LIFE_TIME_JWT | 15 | The time in minutes for the JWT to be valid. | ❌ |
|
|
| SECURITY_LIFE_TIME_1_FA | 15 | Time in minutes after which the token of the first factor will become invalid. | ❌ |
|
|
| SECURITY_JWT_ISSUER | | An identifier that points to the server that created the token. | ✔ |
|
|
| SECURITY_JWT_AUDIENCE | | ID of the audience for which the token is intended. | ✔ |
|
|
|
|
### Hashing Configuration
|
|
|
|
| Variable | Default | Description | Required |
|
|
|---------------------------|---------|-------------------------------------------------------------------------------------------------------------------|----------|
|
|
| SECURITY_HASH_ITERATION | | The number of iterations used to hash passwords in the Argon2 algorithm. At least 10 is recommended for security. | ✔ |
|
|
| SECURITY_HASH_MEMORY | 65536 | The amount of memory used to hash passwords in the Argon2 algorithm (in KB). | ✔ |
|
|
| SECURITY_HASH_PARALLELISM | | Parallelism determines how many of the memory fragments divided into strips will be used to generate a hash. | ✔ |
|
|
| SECURITY_HASH_SIZE | 32 | The size of the output hash generated by the password hashing algorithm. | ✔ |
|
|
| SECURITY_HASH_TOKEN | | Additional protection for Argon2. Recommended to install a token for added security. | ❌ |
|
|
| SECURITY_SALT_SIZE | 16 | The size of the salt used to hash passwords. | ✔ |
|
|
|
|
### OAuth2 Configuration
|
|
|
|
To set up the `redirect URL` when registering and logging in using OAuth 2, use the following format:
|
|
|
|
```
|
|
"{schema}://{domain}{portString}{ACTUAL_SUB_PATH}/api/v1/Auth/OAuth2"
|
|
```
|
|
|
|
** Where:**
|
|
|
|
- `{schema}` is the protocol you are using (`http` or `https').
|
|
- `{domain}` is your domain (for example, `mydomain.com ` or IP address).
|
|
- `{portString}` is a port string that is only needed if your application is running on a non—standard port (for
|
|
example, `:8080`). If you use standard ports (`80` for `http` and `443` for `https`), this parameter can be omitted.
|
|
- `{ACTUAL_SUB_PATH}` is the path to your API that you specify in the settings. If it ends with `/api', then don't add `
|
|
/api` at the end of the URL.
|
|
|
|
**Examples:**
|
|
|
|
- If you have `ACTUAL_SUB_PATH = my_subpath/api`, then the `redirect URL` will be:
|
|
- `https://mydomain.com/my_subpath/api/v1/Auth/OAuth2`
|
|
|
|
- If your application is on a local server and uses a non-standard port:
|
|
- `http://192.168.1.5:8080/my_subpath/api/v1/Auth/OAuth2 `
|
|
|
|
**Important:**
|
|
|
|
- If your application is not located behind a proxy server, then the parameter `{ACTUAL_SUB_PATH}` does not need to be
|
|
specified.
|
|
|
|
#### Google
|
|
|
|
| Variable | Default | Description | Required |
|
|
|----------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|----------|
|
|
| GOOGLE_CLIENT_ID | | The client ID provided by Google when you register your application for OAuth. It is necessary for enabling Google login functionality. | ✔ |
|
|
| GOOGLE_CLIENT_SECRET | | The client secret provided by Google, used alongside the client ID to authenticate your application. | ✔ |
|
|
|
|
#### Yandex
|
|
|
|
| Variable | Default | Description | Required |
|
|
|----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------|----------|
|
|
| YANDEX_CLIENT_ID | | The client ID provided by Yandex when you register your application for OAuth. It is required for enabling Yandex login functionality. | ✔ |
|
|
| YANDEX_CLIENT_SECRET | | The client secret provided by Yandex, used alongside the client ID to authenticate your application. | ✔ |
|
|
|
|
#### MailRu
|
|
|
|
| Variable | Default | Description | Required |
|
|
|----------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
|
|
| MAILRU_CLIENT_ID | | The client ID provided by MailRu (Mail.ru Group) when you register your application for OAuth. It is necessary for enabling MailRu login functionality. | ✔ |
|
|
| MAILRU_CLIENT_SECRET | | The client secret provided by MailRu, used alongside the client ID to authenticate your application. | ✔ |
|
|
|
|
# Installation
|
|
|
|
If you want to make a fork of this project or place the Backend application on your hosting yourself, then follow the
|
|
instructions below.
|
|
|
|
1. [Docker Installation](#docker-installation)
|
|
2. [Docker Self Build](#docker-self-build)
|
|
3. [Manual Installation](#manual-installation)
|
|
4. [Self Build](#self-build)
|
|
|
|
## Docker Installation
|
|
|
|
**Requirements**
|
|
|
|
- Docker
|
|
|
|
To launch the application, pull out the application image:
|
|
|
|
```bash
|
|
docker pull winsomnia/mirea-backend:latest
|
|
```
|
|
|
|
Next, you need to fill in the required fields inside.env and pass it when the container is started:
|
|
|
|
```bash
|
|
docker run -d --name mirea-backend -p 8080 \
|
|
--restart=on-failure:10 \
|
|
-v mirea-data:/data \
|
|
-e PATH_TO_SAVE=/data \
|
|
-e .env \
|
|
winsomnia/mirea-backend:latest
|
|
```
|
|
|
|
Using the `--name` option, you can specify your container name, for example: `--name mirea`.
|
|
|
|
With the `-p` option, you can specify the port you need: `-p 80:8080`.
|
|
|
|
It is necessary to tell the application exactly where to save the data so that it does not disappear when the container
|
|
is deleted.
|
|
|
|
To do this, replace the `-v` option, where you need to specify the path to the data on the host first, and then using
|
|
`:` specify the path inside the container. `-v /nas/mirea/backend:/myfolder`.
|
|
|
|
At the same time, do not forget to replace inside [.env](.env) `PATH_TO_SAVE` with what you specify in the `-v` option.
|
|
In our case, it will be `PATH_TO_SAVE=/myfolder`.
|
|
|
|
That's it, the container is running!
|
|
|
|
## Docker Self Build
|
|
|
|
- Docker
|
|
|
|
To build your own application image, run:
|
|
|
|
```bash
|
|
docker build -t my-name/mirea-backend:latest .
|
|
```
|
|
|
|
Where `-t` indicates the name and version of the image. You can specify their `your-name/image-name:version`.
|
|
|
|
Now the image is ready. To launch the container, refer to [Docker Installation](#docker-installation), do not forget to
|
|
specify the name of the image that you have built.
|
|
|
|
## Manual Installation
|
|
|
|
**Requirements**
|
|
|
|
- ASP.NET Core runtime 8.0
|
|
|
|
To install using a pre-built application, follow these steps:
|
|
|
|
1. [Install ASP.NET](#install-aspnet)
|
|
2. [Download Package](#download-package)
|
|
3. [Run](#run)
|
|
|
|
### Install ASP.NET
|
|
|
|
Installation ASP.NET it depends on the specific platform.
|
|
Go to [Microsoft website](https://dotnet.microsoft.com/download/dotnet/8.0 ) and find your platform. Follow the
|
|
installation instructions.
|
|
|
|
### Download Package
|
|
|
|
The latest versions of the packages can be found
|
|
in [releases](https://git.winsomnia.net/Winsomnia/MireaBackend/releases ). If there is no build for your platform,
|
|
go [to the Self Build section](#self-build).
|
|
|
|
### Run
|
|
|
|
Go to the directory with the application.
|
|
|
|
Don't forget to set up [required configurations](#environment-variables) for the application to work.
|
|
|
|
Run the program.
|
|
|
|
`Debian/Ubuntu`
|
|
|
|
```bash
|
|
dotnet Mirea.Api.Endpoint.dll
|
|
```
|
|
|
|
## Self Build
|
|
|
|
Requirements
|
|
|
|
- ASP.NET Core runtime 8.0
|
|
- .NET 8.0 sdk (for build)
|
|
- git
|
|
|
|
To build your own version of the program, follow these steps:
|
|
|
|
1. [Install .NET SDK](#install-net-sdk)
|
|
2. [Clone The Repository](#clone-the-repository)
|
|
3. [Build Self Release](#build-self-release)
|
|
|
|
### Install NET SDK
|
|
|
|
Installation.The NET SDK depends on the specific platform.
|
|
Go to [Microsoft website](https://dotnet.microsoft.com/download/dotnet/8.0 ) and find your platform. Follow the
|
|
installation instructions.
|
|
|
|
### Clone The Repository
|
|
|
|
Install git in advance or clone the repository in another way.
|
|
|
|
> ⚠ It is advisable to clone the `master` branch, the rest of the branches may work unstable.
|
|
|
|
```bash
|
|
git clone https://git.winsomnia.net/Winsomnia/MireaBackend.git \
|
|
cd MireaBackend
|
|
```
|
|
|
|
### Build Self Release
|
|
|
|
Go to the project folder. Restore the dependencies using the command:
|
|
|
|
```bash
|
|
dotnet restore
|
|
```
|
|
|
|
Let's move on to the assembly.
|
|
|
|
Variables:
|
|
|
|
- `<platform>` — Platform for which the build will be performed.
|
|
- `<arch>` — System architecture. Example: x86 x64.
|
|
- `<output directory>` — The directory where the assembly will be saved.
|
|
|
|
```bash
|
|
dotnet publish "./Endpoint/Endpoint.csproj" -c Release -r <platform>-<arch> -framework net8.0 -o <output directory> /p:SelfContained=false /p:UseAppHost=false
|
|
```
|
|
|
|
The release is now in the directory you specified. To run it, look at the [startup instructions](#run).
|
|
|
|
# Contribution and Feedback
|
|
|
|
You can contribute to the project by creating pull requests. Any feedback is welcome to improve the project.
|
|
|
|
# License
|
|
|
|
This project is licensed under the [MIT License](LICENSE.txt).
|