mirror of
https://github.com/GaMeNu/HFCNotificator.git
synced 2024-11-16 07:14:52 +02:00
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# Home Front Command Notificator
|
|
## A bot to send Discord notifications for HFC alerts
|
|
### Created by GaMeNu and yrrad8
|
|
|
|
> [!WARNING]\
|
|
> This bot is unofficial! The public instance may experience downtimes, and there may be issue with the code. Please do not rely on it alone!
|
|
|
|
> [!CAUTION]\
|
|
> As of September 2024, the public instance of HFCNotificator is offline, as none of the project maintainers are available to maintain it. Feel free to host your own instance!
|
|
|
|
## Table of Contents
|
|
- [What is this?](#what-is-this)
|
|
- [Setup](#setup)
|
|
- [Command Documentation](#command-documentation)
|
|
- [About Self Hosting](#self-hosting)
|
|
- [Important Links](#links)
|
|
|
|
## What is This?
|
|
This is a bot that connects to the HFC's servers and sends real-time notifications about alerts in Israel.
|
|
|
|
The bot's development began in 2023, at the start of the Simchat Torah (Iron Swords) War, and is developed by GaMeNu and yrrad8.
|
|
The bot aims to be relatively fast, reliable, and available for easy hosting and forking.
|
|
|
|
Feel free to send suggestions and bug reports through our [discord server](https://discord.gg/K3E4a5ekNy), or just fork the bot and add what you want yourself!
|
|
|
|
|
|
## Setup
|
|
Invite the bot to a server, and /register a channel, and you're ready to go!
|
|
|
|
Alternatively, you can /register a Direct Message / Group DM channel to receive alerts directly!
|
|
|
|
Please do note that the bot instance listed under the [links section](#links) is hosted on a private machine, and may be a bit slow. It is recommended to [host your own instance](#self-hosting), if possible.
|
|
|
|
## Command documentation
|
|
#### /register
|
|
Run in a channel to register it to receive alerts
|
|
#### /unregister
|
|
Run in a registered channel to stop it from receiving alerts
|
|
#### /latest \<time\> \<unit\> \[page\]
|
|
Get the latest alerts from up to a certain time back.
|
|
#### /about
|
|
Get some info about the bot itself
|
|
#### /info
|
|
Get info about the system and client
|
|
|
|
### Location commands
|
|
#### /locations add \<id\>
|
|
Register a location to receive alerts from
|
|
#### /locations remove \<id\>
|
|
Remove a location to receive alerts from
|
|
#### /locations clear \<id\>
|
|
Clear all registered locations (Get alerts from everywhere)
|
|
#### /locations list \[search\] \[page\]
|
|
List all valid locations
|
|
#### /locations registered \[search\] \[page\]
|
|
List all registered locations
|
|
|
|
## Self-hosting
|
|
### Requirements
|
|
#### Required PyPI packages (run each with `pip install`)
|
|
**Note:** On Windows you will have to write `python -m pip` instead of `pip` at the beginning of pip install commands
|
|
|
|
**Note:** as of 2023-10-23, discord.py seems to not install properly for Python 3.11 and above.
|
|
The fix we've found is to first install the beta version of package `aiohttp` separately (`aiohttp==3.9.0b0`).
|
|
|
|
Please use the requirements files (`pip install -r`):
|
|
|
|
Python 3.10 and below:
|
|
```
|
|
(python -m) pip install -r requirements.txt
|
|
```
|
|
|
|
Python 3.11 and above:
|
|
```
|
|
(python -m) pip install -r requirements-3_11.txt
|
|
```
|
|
|
|
#### Other requirements
|
|
- A discord bot app ([tutorial](https://github.com/discord-apps/bot-tutorial#how-to-create-an-application))
|
|
- MySQL Server (Download link: https://dev.mysql.com/downloads/mysql/) (also available on most package repositories)
|
|
|
|
### Local data:
|
|
#### .env file
|
|
Save the following to a file named ".env", and replace the angled brackets with the matching data. Do note that it has to be on the same directory as `main.py`.
|
|
|
|
```env
|
|
TOKEN = <Discord bot token>
|
|
AUTHOR_ID = <Your Discord user ID>
|
|
|
|
DB_USERNAME = <MySQL database username>
|
|
DB_PASSWORD = <MySQL database password>
|
|
```
|
|
|
|
#### botinfo file
|
|
In botinfo.json, change the "maintainer" value (default is "GaMeNu (@gamenu)") to your username, and maybe add contact information. This is in order to allow others to contact you about issues with your specific instance, and will be publicly available through /info.
|
|
|
|
**Make sure to not write any personal/private information there!**
|
|
|
|
|
|
## Links
|
|
[GitHub](https://github.com/GaMeNu/HFCNotificator)
|
|
|
|
[Official Bot Invite Link](https://discord.com/api/oauth2/authorize?client_id=1160344131067977738&permissions=0&scope=applications.commands%20bot)
|
|
|
|
[Bot Profile (Use to open a Direct Message with the bot)](https://discord.com/users/1160344131067977738)
|
|
|
|
[HFC Website](https://www.oref.org.il/)
|
|
|
|
[Support Server](https://discord.gg/K3E4a5ekNy)
|
|
|
|
|
|
|