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

docs: update

Browse Source
This commit is contained in:
Polianin Nikita 2024-11-04 02:39:45 +03:00
parent e977de3e4f
commit 5f36e0f75b
2 changed files with 164 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
.env
View File

@ -21,6 +21,8 @@ PATH_TO_SAVE=
# The actual sub path to the api
# string
# (optional)
# If the specified path ends with "/api", the system will avoid duplicating "api" in the final URL.
# This allows flexible API structuring, especially when running behind a reverse proxy or in containerized environments.
ACTUAL_SUB_PATH=
# The sub path to the swagger
@ -114,4 +116,48 @@ SECURITY_HASH_TOKEN=
# The size of the salt used to hash passwords
# integer
# The salt is a random value added to the password before hashing to prevent the use of rainbow hash tables and other attacks.
SECURITY_SALT_SIZE=16
SECURITY_SALT_SIZE=16
### OAuth2
#### GOOGLE
# The client ID for Google OAuth
# string
# This is the client ID provided by Google when you register your application for OAuth.
# It's necessary for enabling Google login functionality.
GOOGLE_CLIENT_ID=
# The client secret for Google OAuth
# string
# This is the client secret provided by Google, used alongside the client ID to authenticate your application.
# Make sure to keep it confidential.
GOOGLE_CLIENT_SECRET=
#### Yandex
# The client ID for Yandex OAuth
# string
# This is the client ID provided by Yandex when you register your application for OAuth.
# It's required for enabling Yandex login functionality.
YANDEX_CLIENT_ID=
# The client secret for Yandex OAuth
# string
# This is the client secret provided by Yandex, used alongside the client ID to authenticate your application.
# Keep it confidential to ensure the security of your app.
YANDEX_CLIENT_SECRET=
#### MailRu
# The client ID for MailRu OAuth
# string
# This is the client ID provided by MailRu (Mail.ru Group) when you register your application for OAuth.
# It's necessary for enabling MailRu login functionality.
MAILRU_CLIENT_ID=
# The client secret for MailRu OAuth
# string
# This is the client secret provided by MailRu, used alongside the client ID to authenticate your application.
# Keep it confidential to ensure the security of your app.
MAILRU_CLIENT_SECRET=

148
README.md
View File

@ -11,48 +11,126 @@ The main task is to provide convenient and flexible tools for accessing the sche
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.
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.
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.
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.
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.
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.
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.
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.
| Variable | Default | Description | Required |
|---------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| PATH_TO_SAVE | Current folder | The path to save the data. Saving logs (if the full path is not specified), databases (if Sqlite), and other data that should be saved in a place other than where the program is launched. | ✔ |
| SECURITY_SIGNING_TOKEN | ❌ | JWT signature token. This token will be used to create and verify the signature of JWT tokens. The token must be equal to 64 characters. | ✔ |
| SECURITY_ENCRYPTION_TOKEN | ❌ | Token for JWT encryption. This token will be used to encrypt and decrypt JWT tokens. The token must be equal to 32 characters. | ✔ |
| SECURITY_LIFE_TIME_RT | 1440 | Time in minutes after which the Refresh Token will become invalid. | ❌ |
| SECURITY_LIFE_TIME_JWT | 15 | Time in minutes after which the JWT token will become invalid. | ❌ |
| 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. | ✔ |
| SECURITY_HASH_ITERATION | ❌ | The number of iterations used to hash passwords in the Argon2 algorithm. | ✔ |
| SECURITY_HASH_MEMORY | ❌ | The amount of memory used to hash passwords in the Argon2 algorithm. | ✔ |
| 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. We recommend installing a token so that even if the data is compromised, an attacker cannot brute force a password without a token. | ❌ |
| SECURITY_SALT_SIZE | 16 | The size of the salt used to hash passwords. The salt is a random value added to the password before hashing to prevent the use of rainbow hash tables and other attacks. | ❌ |
### 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.
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)
@ -86,11 +164,14 @@ Using the `--name` option, you can specify your container name, for example: `--
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.
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`.
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`.
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!
@ -106,7 +187,8 @@ 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.
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
@ -123,11 +205,14 @@ To install using a pre-built application, follow these steps:
### 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.
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).
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
@ -160,7 +245,8 @@ To build your own version of the program, follow these steps:
### 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.
Go to [Microsoft website](https://dotnet.microsoft.com/download/dotnet/8.0 ) and find your platform. Follow the
installation instructions.
### Clone The Repository