diff --git a/.media/icon-128x128_round.png b/.media/icon-128x128_round.png new file mode 100644 index 0000000..24c1abe Binary files /dev/null and b/.media/icon-128x128_round.png differ diff --git a/.media/screenshot-1.png b/.media/screenshot-1.png new file mode 100644 index 0000000..ced551a Binary files /dev/null and b/.media/screenshot-1.png differ diff --git a/.media/screenshot-2.png b/.media/screenshot-2.png new file mode 100644 index 0000000..67c11c7 Binary files /dev/null and b/.media/screenshot-2.png differ diff --git a/.media/screenshot-3.png b/.media/screenshot-3.png new file mode 100644 index 0000000..20d75fa Binary files /dev/null and b/.media/screenshot-3.png differ diff --git a/README.md b/README.md index 9756053..1622fe7 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,21 @@ +
+ +![](.media/icon-128x128_round.png) + # Greed -A [customizable](/config/template_config.toml), [multilanguage](/strings) Telegram shop bot with [Telegram Payments support](https://core.telegram.org/bots/payments)! +[Customizable](/config/template_config.toml) and [multilanguage](/strings) Telegram shop bot with [Telegram Payments support](https://core.telegram.org/bots/payments) -\[ [**Documentation**](https://github.com/Steffo99/greed/wiki) | [Support](https://github.com/Steffo99/greed/issues/new/choose) \] +
-![](https://i.imgur.com/FdT2tRV.png) +## Links +  +[![Documentation](https://img.shields.io/badge/docs-wiki-blue)](/docs/README.md) -![](https://i.imgur.com/rDYWdUB.png) +## Screenshots -![](https://i.imgur.com/9plMzO6.png) +![](.media/screenshot-1.png) + +![](.media/screenshot-2.png) + +![](.media/screenshot-3.png) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2ba357b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,286 @@ +# Documentation + +> [!WARNING] +> +> First of all, please note that this bot is a **proof-of-concept**! +> No guarantees are provided if you use it, including guarantees of support, so use it in the real world at your own risk! + +## History + +Greed was developed as an [high school finals project](https://docs.google.com/document/d/1f4MKVr0B7RSQfWTSa_6ZO0LM4nPpky_GX_qdls3EHtQ/edit) and then continued independently of the school thanks to the contributors of various developers, who you see credited on each individual commit. + +The bot has since then ceased to be developed, but issues and pull request still are sometimes handled on the creator's free time. + +## Features + +Greed supports: + +- for **users**: + - creating an order + - listing the status of all orders + - adding more funds to the bot's wallet + - via cash + - via Telegram Payments + - changing language + - displaying information and help about the bot + +- for **store managers**: + - creating / editing / deleting products + - receiving a live stream of orders to fulfill or refund as messages + - manually adding funds to an user + - displaying the list of performed transactions + - exporting the list of performed transactions as a CSV file + - adding other users as managers and specifying their permissions + +## Installation via Docker Engine + +This installation procedure assumes you are on a system with `docker` installed, with a supported CPU architecture. + +### Requirements + +* [Docker Engine](https://docs.docker.com/get-docker/) +* An Internet connection +* A Telegram bot token (obtainable at [@Botfather](https://t.me/Botfather)) +* A payment provider token (obtainable by [connecting a provider with your bot](https://t.me/Botfather)) + +### Steps + +1. Run a container using the project's Docker image: + ```console + # docker run --volume "$(pwd)/config:/etc/greed" --volume "$(pwd)/strings:/usr/src/greed/strings" --volume "$(pwd)/data:/var/lib/greed" ghcr.io/steffo99/greed + ``` + +1. Edit the configuration file `config.toml` that was created in the `strings` directory, adding your bot and payment tokens to it: + ```console + # nano config/config.toml + ``` + (Press **Ctrl+X** and then two times **Enter** to save and quit `nano`.) + +1. _Optional:_ customize the files in the `strings` folder for custom messages. + +1. Start the bot: + ```console + python -OO core.py + ``` + +1. Open Telegram, and send a `/start` command to your bot to be automatically promoted to 💼 Manager. + +1. Stop the bot by pressing **Ctrl+C**. + +### Running the bot + +After the installation, to run the bot, you'll need to: + +1. Run its Docker container from the same directory you installed it from: + ```console + # docker run --volume "$(pwd)/config:/etc/greed" --volume "$(pwd)/strings:/usr/src/greed/strings" --volume "$(pwd)/data:/var/lib/greed" ghcr.io/steffo99/greed + ``` + +### Keep the bot running + +If you want to keep the bot open even after you closed your terminal window, you'll need to pass the appropriate arguments to the docker command: + +1. Set the Docker container to always restart and to detach on successful start: + ```console + # docker run --detach --restart always --volume "$(pwd)/config:/etc/greed" --volume "$(pwd)/strings:/usr/src/greed/strings" --volume "$(pwd)/data:/var/lib/greed" ghcr.io/steffo99/greed + ``` + +### Updating + +To update the bot, run the following commands: + +1. Find the ID of the Docker container of the bot: + ```console + # docker container ls + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + abcdefabcdef ghcr.io/steffo99/greed "python -OO core.py" 6 seconds ago Up Less than a second relaxed_hypatia + ``` + +1. Stop the Docker container of the bot: + ```console + # docker container stop abcdefabcdef + ``` + +1. Remove the Docker container of the bot: + ```console + # docker container rm abcdefabcdef + ``` + +1. Pull the latest Docker image of the bot: + ```console + # docker pull ghcr.io/steffo99/greed:latest + ``` + +1. Restart the bot with the newly downloaded image: + ```console + # docker run --detach --restart always --volume "$(pwd)/config:/etc/greed" --volume "$(pwd)/strings:/usr/src/greed/strings" --volume "$(pwd)/data:/var/lib/greed" ghcr.io/steffo99/greed + ``` + +## Installation via pip + +This installation procedure assumes you are on a Linux system, using `bash`, and with `python` installed. + +### Requirements + +* [Git](https://git-scm.com/) +* [Python 3.8 (or higher)](https://www.python.org/) +* An Internet connection +* A Telegram bot token (obtainable at [@Botfather](https://t.me/Botfather)) +* A payment provider token (obtainable by [connecting a provider with your bot](https://t.me/Botfather)) + +Consider renting a virtual private server (VPS) to host the bot on; a cheap one should do, as greed is pretty lightweight! :) + +### Steps + +1. Download the project files by running: + ```console + $ git clone https://github.com/Steffo99/greed.git + ``` + +1. Enter the newly created folder: + ```console + $ cd greed + ``` + +1. Create a new venv: + ```console + $ python3 -m venv venv + ``` + +1. Activate the venv: + ```console + $ source venv/bin/activate + ``` + +1. Install the project requirements: + ```console + $ pip install -r requirements.txt + ``` + +1. _Optional:_ For colored console output, install [coloredlogs](https://pypi.org/project/coloredlogs/): + ```console + $ pip install coloredlogs + ``` + +1. Generate the configuration file: + ```console + $ python -OO core.py + ``` + +1. Edit the configuration file `config.toml`, adding your bot and payment tokens to it: + ```console + $ nano config/config.toml + ``` + (Press **Ctrl+X** and then two times **Enter** to save and quit `nano`.) + + > Beware to not enter your configuration in the `template_config.toml` file, as it will be ignored and may cause trouble when updating. + +1. _Optional:_ customize the files in the `strings` folder for custom messages. + +1. Start the bot: + ```console + $ python -OO core.py + ``` + +1. Open Telegram, and send a `/start` command to your bot to be automatically promoted to 💼 Manager. + +1. Stop the bot by pressing **Ctrl+C**. + +### Running the bot + +After the installation, to run the bot, you'll need to: + +1. Activate the venv (if it has not already been activated in the current console session): + ```console + $ source venv/bin/activate + ``` + +1. Start the bot: + ```bash + $ python -OO core.py + ``` + +### Keep the bot running + +If you want to keep the bot open even after you closed your terminal window, you'll need to use an external program, such as: + +- `screen` (easier, but doesn't restart automatically) +- `systemd` (recommended, but more complex) + +#### `screen` + +1. Open a `screen` that will be running the bot with the following command: + ```console + $ screen venv/bin/python -OO core.py + ``` + To safely detach the screen, press Ctrl+A and then Ctrl+D. + +#### `systemd` + +Assuming you downloaded `greed` in `/srv/greed`: + +1. Create a new user named `greed`: + ```console + $ useradd greed --system + ``` + +1. Give ownership of the greed folder you downloaded earlier to the `greed` user: + ```console + $ chown -R greed: /srv/greed + ``` + +1. Create a new file in `/etc/systemd/system` named `bot-greed.service` with the following contents: + ```ini + [Unit] + Name=bot-greed + Description=Greed Bot + Wants=network-online.target + After=network-online.target nss-lookup.target + + [Service] + Type=exec + User=greed + WorkingDirectory=/srv/greed + ExecStart=/srv/greed/venv/bin/python -OO /srv/greed/core.py + Environment=PYTHONUNBUFFERED=1 + + [Install] + WantedBy=multi-user.target + ``` + +1. Start the `bot-greed` service: + ```console + $ systemctl start bot-greed + ``` + +1. If everything goes well, enable the bot-greed service, so it will automatically start on a reboot: + ```console + $ systemctl enable bot-greed + ``` + +### Updating + +To update the bot, run the following commands: + +```console +$ git stash +$ git pull +$ git stash pop +``` + +> If you're using an older version of greed, you may need to recreate the configuration, as greed doesn't use `config.ini` anymore and but uses `config.toml` instead. + +## Technical structure + +The bot is composed of two parts: + +- `core.py`, which handles communication with Telegram and dispatches updates to the workers +- `worker.py`, which handles the conversation flow for a single user, and runs on a separate thread for each conversation + +Other resources used by the bot are: + +- `utils.py`, containing utility methods +- `nuconfig.py`, containing the configuration loader +- `database.py`, handling interactions with a SQLite or PostgreSQL database +- `localization.py` and `strings/*`, managing the bot's languages +- `config/*`, initially containing the template to generate the configuration file, then also the configuration file itself after the bot has been run once