162 lines
5.9 KiB
Markdown
162 lines
5.9 KiB
Markdown
# Albatrobot
|
|
|
|
Albatrobot is a personal project born as a bot to dice rolling only, but has
|
|
since then evolved with the addition of more functions (most of which is
|
|
useless). But I like it even if it is substantially bloat.
|
|
|
|
## Installation and usage
|
|
|
|
### Installation
|
|
|
|
To install Albatrobot, follow those steps.
|
|
1. Download the source code
|
|
2. Move it to the installation path of your choice and run
|
|
```
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
python3 -m pip install -r requirements.txt
|
|
```
|
|
3. Configure the bot as you like (see [Configuration](#configuration)
|
|
paragraph).
|
|
|
|
## Configuration
|
|
|
|
All the required configuration is in `settings.ini` file, that can be edited
|
|
either manually or through the configuration script `setup.py`. The first way
|
|
is recommended one.
|
|
|
|
The settings in `settings.ini` are described below.
|
|
|
|
* `Token`: token to connect the software to the bot user on Telegram server.
|
|
Seealso <https://core.telegram.org/bots#3-how-do-i-create-a-bot> and
|
|
<https://core.telegram.org/bots/api#authorizing-your-bot>.
|
|
* `AuthUsers`: user IDs of the users allowed to use the bot. The numbers must
|
|
be separated by commas.
|
|
* `MsgCooldown`: minimum time in seconds between two following uses of commands
|
|
`/Easter` or `/Christmas` by the same user. The time is the same, but it is
|
|
considered separately for the two commands.
|
|
* `CitePath`: path of the document containing the citations for `/Easter`
|
|
command.
|
|
* `ImgPath`: path containing the images for `/Christmas` command.
|
|
|
|
If you choose to use the configuration script, you must run it in the
|
|
installation path as
|
|
|
|
python3 setup.py
|
|
|
|
### Usage
|
|
|
|
#### Manual boot
|
|
|
|
You can boot Albatrobot with the following command:
|
|
|
|
cd <installation path> && source .venv/bin/activate && ./main.py
|
|
|
|
However, running Albatrobot like that is not recommended (except for testing
|
|
purposes). If you do that, you can then stop the bot with `Ctrl + C`.
|
|
|
|
#### Automatic boot
|
|
|
|
Albatrobot can be automatically run at system boot by adding the following
|
|
command in `crontab` queue:
|
|
|
|
@reboot sleep 10 && cd <installation path> && ./main.py > /tmp/albatrobot.txt 2>&1
|
|
|
|
To do so, run `crontab -e` and add the above line to the file that will be
|
|
opened, then save and close.
|
|
|
|
If you run Albatrobot this way - the recommended one - consider the following.
|
|
|
|
* `sleep 10` adds a delay of 10 seconds. It is necessary to allow the system
|
|
to set the network up and prevents errors due to impossibility to connect to
|
|
the Internet and to Telegram APIs. You can change the time to comply with
|
|
your necessities.
|
|
* If Albatrobot can't be launched, some error information should be saved in
|
|
`/tmp/albatrobot.txt`.
|
|
|
|
You can stop Albatrobot by killing its process. I will add a better way in the
|
|
future.
|
|
|
|
## Common problems
|
|
|
|
### When I try to start the bot Python exits with an error
|
|
|
|
Check:
|
|
1. that the configuration file content is in the correct format and contains
|
|
the correct information (see paragraph [Configuration](#configuration));
|
|
2. that you have installed the required libraries (see paragraph
|
|
[Installation](#installation));
|
|
3. that you have activate the virtual environment (see paragraph
|
|
[Installation](#installation));
|
|
4. that the virtual environment has not been changed after the installation.
|
|
|
|
In the first three cases, the solution is self-explaining. In the fourth, the
|
|
simplest way is to just delete the virtual environment and recreate it. Just
|
|
run the following commands in the installation path:
|
|
|
|
rm -rf .venv python3 -m venv .venv source .venv/bin/activate python3 -m pip install -r requirements.txt
|
|
|
|
This does not cause any data loss.
|
|
|
|
### The Albatrobot seems correctly booted but on Telegram it doesn't work or behaves oddly
|
|
|
|
Check:
|
|
1. that you have used the correct token (see paragraph
|
|
[Configuration](#configuration));
|
|
2. that only one instance of the albatrobot is active for the same Telegram bot
|
|
user
|
|
|
|
If none of the above solution has effect, try the ones of those suggested for
|
|
[Python errors](#when-i-try-to-start-the-bot-python-exits-with-an-error).
|
|
|
|
### Albatrobot says that there are no avilable citations or images
|
|
|
|
Check:
|
|
1. that there are available citations and images;
|
|
2. that citations and images are in supported formats;
|
|
3. that in the configuration the correct paths are set.
|
|
|
|
## Some notes
|
|
|
|
### About language
|
|
|
|
Albatrobot was not originally developed nor used in English and the translation
|
|
may contain mistakes. Sorry for that. If you want so, you can help improving
|
|
it.
|
|
|
|
### About the repository
|
|
|
|
This git repository does not contain all the project's development history
|
|
because of two causes.
|
|
1. At the beginning, the project was not tracked with git.
|
|
2. I chose to redistribute the software after much time of development, so the
|
|
original archive contained some data that I didn't want nor could publish.
|
|
But at that time it was way easier to create a new archive than purging
|
|
those data from the original one. And the original archive contained many
|
|
completely unuseful files.
|
|
|
|
## License
|
|
|
|
Albatrobot is proudly [free
|
|
software](https://www.gnu.org/philosophy/free-sw.html#four-freedoms) (as both
|
|
in "free speech" and "free beer") and always will be, as it is released under
|
|
[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0-standalone.html) license.
|
|
Its source code is publicly available at
|
|
[Disroot](https://git.disroot.org/bursapastoris/albatrobot).
|
|
|
|
## Disclaimer
|
|
|
|
Albatrobot is free software, but it works interacting with
|
|
[Telegram](https://telegram.org)'s servers and API. Most of Telegram's clients
|
|
are distributed under a free license, but *all Telegram's servers' code is
|
|
proprietary software* and as such it yields unjust power over its users and
|
|
cannot be trusted. *Albatrobot's development does not want to promote non-free
|
|
software* and is just an instructive hobby.
|
|
|
|
Please, *at least* for communication that must be kept private or secret do not
|
|
use Telegram. Use only free software and free protocols instead.
|
|
|
|
* * *
|
|
|
|
|