mirrors/untisbot-discord
1
0
Fork 0
mirror of https://github.com/bytedream/untisbot-discord.git synced 2025-06-27 00:10:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

README.md rewrite and internal refactoring

Browse Source
This commit is contained in:
ByteDream
2020-11-26 22:01:13 +01:00
parent dd883b71e2
commit fa37ff58f3
6 changed files with 120 additions and 422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
README.md
View File

@ -3,51 +3,60 @@
**UntisBot** is a java programmed discord bot, which uses the [WebUntis](https://webuntis.com/) timetable software / api to automatically sends messages when the timetable from a given account or class changes.
You can invite the bot right [here](https://github.com/ByteDream/untisbot-discord/releases/tag/v1.0/UntisBot-1.0.jar) or [host it yourself](#Self-hosting).
<p align="center">
<a href="#Commands">Commands</a>
•
<a href="#Self-hosting">Self-hosting</a>
•
<a href="#Language">Language</a>
•
<a href="#Licence">Licence</a>
</p>
## Commands
The default prefix for the bot is `!untis `, so you have to call every command with `!untis <command>`.
To see all available commands and get infos about it, simply type `help`
To see all available commands and get infos about it, simply type `help`.
`channel` - In the channel where this command is entered, the bot shows the timetable changes | eg. `channel`.
`<>` are required arguments, `[]` is optional.
`clear` - Clears the given untis data, given from the `data` command | eg. `clear`.
`data <username> <password> <login page url> [class name]` - Sets the data with which the bot logs in to untis and checks for timetable changes. The data is stored encrypted on the server.
`username` and `password` are the normal untis login data with which one also logs in to the untis website / app. To gain the login page url you have to go to webuntis.com, type in your school and choose it.
Then you will be redirected to the untis login page, The url of this page is the login page url, for example `https://example.webuntis.com/WebUntis/?school=myschool#/basic/main`.
`class name` is just the name of the class you want to check (eg. `12AB`). If `class name` is not specified, the bot tries to get the default class which is assigned to the given account.
eg. `data myname secure https://example.webuntis.com/WebUntis/?school=example#/basic/main 12AB`.
`help <command>` - Displays help to a given command | eg. `help data`.
`language <language>` - Changes the language in which the timetable information are displayed. Currently only 'de' (german) and 'en' (english) are supported | eg. `language de` | default: `en`.
`prefix <new prefix>` - Changes the prefix with which commands are called | eg. `prefix $` | default: `!untis `.
`stats` - Displays a message with some stats (total cancelled lessons, etc.) | eg. `stats`.
`<>` = required; `[]` = optional
| command | usage | example | default |
| --- | --- | --- | --- |
| `channel` | In the channel where this command is entered, the bot shows the timetable changes | `channel` | -
| `clear` | Clears the given untis data, given from the `data` command | `clear` | -
| `data <username> <password> <login page url> [class name]` | Sets the data with which the bot logs in to untis and checks for timetable changes. The data is stored encrypted on the server. `username` and `password` are the normal untis login data with which one also logs in to the untis website / app. To gain the login page url you have to go to webuntis.com, type in your school and choose it. Then you will be redirected to the untis login page, The url of this page is the login page url, for example `https://example.webuntis.com/WebUntis/?school=myschool#/basic/main`. `class name` is just the name of the class you want to check (eg. `12AB`). If `class name` is not specified, the bot tries to get the default class which is assigned to the given account. | `data myname secure https://example.webuntis.com/WebUntis/?school=example#/basic/main 12AB` | - |
| `help` | Displays help to a given command | `help data` | - |
| `language <language>` | Changes the language in which the timetable information are displayed. Currently only `de` (german) and `en` (english) are supported | `language de` | `en` |
| `prefix <new prefix>` | Changes the prefix with which commands are called | `prefix $` | `!untis ` |
| `stats` | Displays a message with some stats (total cancelled lessons, etc.) | `stats` | - |
Note: All commands except for `help <command>` and `<stats>` can only be executed by a member with admin rights.
## Self-hosting
The first step before setting up the bot is to generate a bot token on the [discord developer website](https://discord.com/developers/applications).
A more detailed instruction can be found [here](https://www.writebots.com/discord-bot-token/).
If you want to host **UntisBot** on your own server / pc you have the choice between two types of hosting:
- Run the bot in a [docker container](#Docker)
- Run it [natively](#Natively) on your machine
- Run it [manually](#Manually) on your machine
## Docker
Download this repository with `git clone https://github.com/ByteDream/untisbot-discord.git` and go into the cloned directory.
Then run `docker build -t untisbot-discord .` to build the docker image and if this is done, type `docker run -d --name untisbot-discord -e token=<your discord token> untisbot-discord` to run it.
To run the bot in a docker container, follow the commands below
```bash
git clone https://github.com/ByteDream/untisbot-discord.git
cd untisbot-discord
docker build -t untisbot-discord .
docker run -d --name untisbot-discord -e token=<your discord token> untisbot-discord
```
Note: You can declare more [environment variables](#Run-options-for-docker-container) besides `token`.
## Natively
## Manually
When you run the bot natively you can choose from 2 types of data storage:
When you run the bot manually you can choose from 2 types of data storage:
- [In-memory](#In-memory-storage) (simpler)
- [Database storage](#MariaDB) (MariaDB)
@ -65,28 +74,10 @@ With MariaDB you can store the data safely in a sql database, and they won't be
If you haven't installed MariaDB, you can follow the instructions from [here](https://linuxize.com/post/how-to-install-mariadb-on-ubuntu-18-04/) (this tutorial is for ubuntu, but it should work with every debian distro).
To set up the database, you have two options to choose from.
##### The short one:
To set up the database, you have to execute the following command and replace `<user>` with the sql user which should manage the database.
```bash
mysql --user=<user> --password=<password> -e "CREATE DATABASE Untis;" && wget -qO- https://raw.githubusercontent.com/ByteDream/untisbot-discord/master/src/org/bytedream/untisbot/dockerfiles/database.sql | mysql --user=<user> --password=<password> Untis
mysql -u <user> -p -e "CREATE DATABASE Untis; USE Untis; $(wget -qO- https://raw.githubusercontent.com/ByteDream/untisbot-discord/master/files/database.sql)"
```
Just copy this and replace `<user>` with the sql user which should manage the database and `<password>` with the user's password.
---
##### And the long one:
First you have to connect you with MariaDB. When you are connected, enter the following commands (without the '>'):
```sql
> CREATE DATABASE Untis;
> USE Untis;
> CREATE TABLE Guilds (GUILDID BIGINT NOT NULL, LANGUAGE TINYTEXT, USERNAME TINYTEXT, PASSWORD TEXT, SERVER TINYTEXT, SCHOOL TINYTEXT, KLASSEID SMALLINT, CHANNELID BIGINT, PREFIX VARCHAR(7) DEFAULT '!untis ' NOT NULL, SLEEPTIME BIGINT DEFAULT 3600000 NOT NULL, ISCHECKACTIVE BOOLEAN DEFAULT FALSE NOT NULL, LASTCHECKED DATE);
> CREATE TABLE Stats (GUILDID BIGINT NOT NULL, TOTALREQUESTS INT DEFAULT 0 NOT NULL, TOTALDAYS SMALLINT DEFAULT 0 NOT NULL, TOTALLESSONS INT DEFAULT 0 NOT NULL, TOTALCANCELLEDLESSONS SMALLINT DEFAULT 0 NOT NULL, TOTALMOVEDLESSONS SMALLINT DEFAULT 0 NOT NULL, AVERAGECANCELLEDLESSONS FLOAT DEFAULT 0 NOT NULL, AVERAGEMOVEDLESSONS FLOAT DEFAULT 0 NOT NULL);
> CREATE TABLE AbsentTeachers (GUILDID BIGINT NOT NULL, TEACHERNAME TINYTEXT NOT NULL, ABSENTLESSONS SMALLINT NOT NULL);
```
---
Now you have set up the database and are ready to go. Download the [jar]() and run it with `java -jar UntisBot-1.0.jar <your discord bot token> mariadb`.
@ -96,30 +87,39 @@ The syntax of the following arguments / run option is very simple: `key=value`.
### Run options for docker container
When you start the container you can declare several environment variables:
- `token` (required!) - The discord bot token
- `password` (optional) - Password for the given user | default: `toor`
- `encrypt` (optional) - A password to encrypt the user's untis username and password | default: `password`
When you start the container you can declare several environment variables
| variable | description | default | required |
| --- | --- | --- | --- |
| `token` | The discord bot token | - | yes |
| `password` | Password for the given user | `toor` | no |
| `encrypt` | A password to encrypt the user's untis username and password | `password` | no |
(always remember when declaring a new environment variable `-e` must be prefixed)
---
Example:
- `docker run -d -e token=BLySFrzvz3tAHtquQevY1FF5W8CT0UMyMNmCSUCbJAPdNAmnnqYVBzaPTkz -e password=very_secure untisbot-discord`
```bash
docker run -d -e token=BLySFrzvz3tAHtquQevY1FF5W8CT0UMyMNmCSUCbJAPdNAmnnqYVBzaPTkz -e password=very_secure untisbot-discord
```
### Run options for native hosting
### Run options for manual hosting
There are several arguments to start the bot with:
- `token` (required!) - The discord bot token
- `encrypt` (optional) - A password to encrypt the user's untis username and password | default: `password`
- `lng` (optional) - Path to a language file | default: `` (uses the [internal](src/org/bytedream/untisbot/language.json) language file)
There are several arguments to start the bot with
| variable | description | default | required |
| --- | --- | --- | --- |
| `token` | The discord bot token | - | yes |
| `encrypt` | A password to encrypt the user's untis username and password | `password` | no |
| `lng` | Path to a language file | uses the [internal](src/org/bytedream/untisbot/language.json) language file | no |
The following arguments are only for MariaDB user:
- `user` (optional) - The user who should connect to the mariadb database | default: `root`
- `password` (optional) - Password for the given mariadb user | default: ``
- `port` (optional) - Port of mariadb | default: `3306`
- `ip` (optional) - IP address of mariadb | default: `127.0.0.1`
| variable | description | default | required |
| --- | --- | --- | --- |
| `user` | The user who should connect to the mariadb database | `root` | no |
| `password` | Password for the given mariadb user | | no |
| `port` | Database port | `3306` | no |
| `user` | IP address of the database | `127.0.0.1` | no |
If you want to use MariaDB as store type you have to add the argument `mariadb` (without any value).
@ -147,13 +147,23 @@ In-memory examples:
MariaDB examples:
- `UntisBot-1.0.jar mariadb token=BLySFrzvz3tAHtquQevY1FF5W8CT0UMyMNmCSUCbJAPdNAmnnqYVBzaPTkz encrypt=super_ultra_secure_password`
- `UntisBot-1.0.jar mariadb token=BLySFrzvz3tAHtquQevY1FF5W8CT0UMyMNmCSUCbJAPdNAmnnqYVBzaPTkz encrypt=super_ultra_secure_password user=untis password=toor`
## Language
The layout for the language file is available [here](src/org/bytedream/untisbot/language.json).
If you want to add a language which isn't supported you can
- Host the bot [yourself](#Self-hosting) and use the `lng` variable (only compatible if you choose [manually hosting](#Manually))
- Create a new [issue](https://github.com/ByteDream/untisbot-discord/issues/new) or [pull request](https://github.com/ByteDream/untisbot-discord/compare)
and paste in your json language. The layout has to be like [this](src/org/bytedream/untisbot/language.json).
Then, after a short check (thx [DeepL](https://www.deepl.com/translator)), I will add it to the repository.
## Dependencies
- Java 8 or higher
- [Discord library](https://github.com/DV8FromTheWorld/JDA) (JDA)
- [Untis library](https://github.com/ByteDream/untis4j) (untis4j)
- [MariaDB client](https://github.com/mariadb-corporation/mariadb-connector-j) (mariadb java client)
- [Database client](https://github.com/mariadb-corporation/mariadb-connector-j) (mariadb java client)
- [Logger](https://github.com/qos-ch/logback) (logback-core and logback-classic)
**_Note_: The [UntisBot jar file](https://github.com/ByteDream/untisbot-discord/releases/tag/v1.0/UntisBot-1.0.jar) and the [Dockerfile](Dockerfile) are containing all dependencies.**
@ -161,4 +171,4 @@ MariaDB examples:
## License
This project is licensed under the Mozilla Public Licence 2.0 - see the [LICENSE](LICENCE) file for more details
This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0) - see the [LICENSE](LICENCE) file for more details.