Winsomnia/MireaBackend
1
0
Fork 0
Code Pull Requests Actions Projects Releases Activity
MireaBackend/README.md

15 KiB
Raw Blame History

MIREA schedule by Winsomnia

NET Release License: 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 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
  2. Docker Self Build
  3. Manual Installation
  4. Self Build

Docker Installation

Requirements

  • Docker

To launch the application, pull out the application image:

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:

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 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:

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, 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
  2. Download Package
  3. Run

Install ASP.NET

Installation ASP.NET it depends on the specific platform. Go to Microsoft website and find your platform. Follow the installation instructions.

Download Package

The latest versions of the packages can be found in releases. If there is no build for your platform, go to the Self Build section.

Run

Go to the directory with the application.

Don't forget to set up required configurations for the application to work.

Run the program.

Debian/Ubuntu

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
  2. Clone The Repository
  3. Build Self Release

Install NET SDK

Installation.The NET SDK depends on the specific platform. Go to Microsoft website 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.

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:

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.
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.

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.