albatrobot/README.md

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 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);
2. that you have installed the required libraries (see paragraph Installation);
3. that you have activate the virtual environment (see paragraph 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);
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.

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 (as both in "free speech" and "free beer") and always will be, as it is released under AGPL-3.0-only license. Its source code is publicly available at Disroot.

Disclaimer

Albatrobot is free software, but it works interacting with Telegram'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.

---