diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb7d12b..c29e8dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,20 @@ Install python dependencies: pip install -e . ``` +This projects uses [Wand](https://docs.wand-py.org) and requires you to install ImageMagick library. + +Debian/Ubuntu: + +``` +sudo apt install libmagickwand-dev +``` + +Arch: + +``` +sudo pacman -S imagemagick +``` + (Optional) If you want to use postgres as a database backend, use the following command to install postgres dependencies alongside those that are necessary: diff --git a/README.md b/README.md index 5be0d3f..4c9f788 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,10 @@ -# Nyx Bot [![Built with matrix-nio](https://img.shields.io/badge/built%20with-matrix--nio-brightgreen)](https://github.com/poljar/matrix-nio) +# Nyx Bot [![Built with matrix-nio](https://img.shields.io/badge/built%20with-matrix--nio-brightgreen)](https://github.com/poljar/matrix-nio) Matrix bot named after [Nyx](https://megamitensei.fandom.com/wiki/Nyx_Avatar). -The rest are from the original template. - ---- - -A template for creating bots with -[matrix-nio](https://github.com/poljar/matrix-nio). The documentation for -matrix-nio can be found -[here](https://matrix-nio.readthedocs.io/en/latest/nio.html). - -This repo contains a working Matrix echo bot that can be easily extended to your needs. Detailed documentation is included as well as a step-by-step guide on basic bot building. - -Features include out-of-the-box support for: - -* Bot commands -* SQLite3 and Postgres database backends -* Configuration files -* Multi-level logging -* Docker -* Participation in end-to-end encrypted rooms - -## Projects using nio-template - -* [anoadragon453/matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot -) - A matrix bot to remind you about things -* [gracchus163/hopeless](https://github.com/gracchus163/hopeless) - COREbot for the Hope2020 conference Matrix server -* [alturiak/nio-smith](https://github.com/alturiak/nio-smith) - A modular bot for @matrix-org that can be dynamically -extended by plugins -* [anoadragon453/msc-chatbot](https://github.com/anoadragon453/msc-chatbot) - A matrix bot for matrix spec proposals -* [anoadragon453/matrix-episode-bot](https://github.com/anoadragon453/matrix-episode-bot) - A matrix bot to post episode links -* [TheForcer/vision-nio](https://github.com/TheForcer/vision-nio) - A general purpose matrix chatbot -* [anoadragon453/drawing-challenge-bot](https://github.com/anoadragon453/drawing-challenge-bot) - A matrix bot to -post historical, weekly art challenges from reddit to a room -* [8go/matrix-eno-bot](https://github.com/8go/matrix-eno-bot) - A bot to be used as a) personal assistant or b) as -an admin tool to maintain your Matrix installation or server -* [elokapina/bubo](https://github.com/elokapina/bubo) - Matrix bot to help with community management -* [elokapina/middleman](https://github.com/elokapina/middleman) - Matrix bot to act as a middleman, for example as a support bot -* [chc4/matrix-pinbot](https://github.com/chc4/matrix-pinbot) - Matrix bot for pinning messages to a dedicated channel - -Want your project listed here? [Edit this -page!](https://github.com/anoadragon453/nio-template/edit/master/README.md) - ## Getting started -See [SETUP.md](SETUP.md) for how to setup and run the template project. +Refer to [SETUP.md](SETUP.md) ## Project structure @@ -56,7 +15,7 @@ The majority of the code is kept inside of the `nyx_bot` folder, which is in itself a [python package](https://docs.python.org/3/tutorial/modules.html), the `__init__.py` file inside declaring it as such. -To run the bot, the `my-project-name` script in the root of the codebase is +To run the bot, the `nyx-bot` script in the root of the codebase is available. It will import the `main` function from the `main.py` file in the package and run it. To properly install this script into your python environment, run `pip install -e .` in the project's root directory. @@ -103,11 +62,7 @@ Otherwise the bot can't function. ### `storage.py` -Creates (if necessary) and connects to a SQLite3 database and provides commands -to put or retrieve data from it. Table definitions should be specified in -`_initial_setup`, and any necessary migrations should be put in -`_run_migrations`. There's currently no defined method for how migrations -should work though. +Contains various Peewee model definitions. ### `callbacks.py` @@ -151,16 +106,29 @@ to the room immediately afterwards with the issue name and link. ### `chat_functions.py` A separate file to hold helper methods related to messaging. Mostly just for -organisational purposes. Currently just holds `send_text_to_room`, a helper -method for sending formatted messages to a room. +organisational purposes. ### `errors.py` -Custom error types for the bot. Currently there's only one special type that's -defined for when a error is found while the config file is being processed. +Custom error types for the bot. -## Questions? +## Projects using nio-template -Any questions? Please ask them in -[#nio-template:amorgan.xyz](https://matrix.to/#/!vmWBOsOkoOtVHMzZgN:amorgan.xyz?via=amorgan.xyz) -and we'll help you out! +* [anoadragon453/matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot +) - A matrix bot to remind you about things +* [gracchus163/hopeless](https://github.com/gracchus163/hopeless) - COREbot for the Hope2020 conference Matrix server +* [alturiak/nio-smith](https://github.com/alturiak/nio-smith) - A modular bot for @matrix-org that can be dynamically +extended by plugins +* [anoadragon453/msc-chatbot](https://github.com/anoadragon453/msc-chatbot) - A matrix bot for matrix spec proposals +* [anoadragon453/matrix-episode-bot](https://github.com/anoadragon453/matrix-episode-bot) - A matrix bot to post episode links +* [TheForcer/vision-nio](https://github.com/TheForcer/vision-nio) - A general purpose matrix chatbot +* [anoadragon453/drawing-challenge-bot](https://github.com/anoadragon453/drawing-challenge-bot) - A matrix bot to +post historical, weekly art challenges from reddit to a room +* [8go/matrix-eno-bot](https://github.com/8go/matrix-eno-bot) - A bot to be used as a) personal assistant or b) as +an admin tool to maintain your Matrix installation or server +* [elokapina/bubo](https://github.com/elokapina/bubo) - Matrix bot to help with community management +* [elokapina/middleman](https://github.com/elokapina/middleman) - Matrix bot to act as a middleman, for example as a support bot +* [chc4/matrix-pinbot](https://github.com/chc4/matrix-pinbot) - Matrix bot for pinning messages to a dedicated channel + +Want your project listed here? [Edit this +page!](https://github.com/anoadragon453/nio-template/edit/master/README.md) diff --git a/SETUP.md b/SETUP.md index 13ae5bc..e6c0391 100644 --- a/SETUP.md +++ b/SETUP.md @@ -2,17 +2,13 @@ _(This requires changing.)_ -nio-template is a sample repository of a working Matrix bot that can be taken -and transformed into one's own bot, service or whatever else may be necessary. -Below is a quick setup guide to running the existing bot. - ## Install the dependencies There are two paths to installing the dependencies for development. ### Using `docker-compose` -It is **recommended** to use Docker Compose to run the bot while +You can use Docker Compose to run the bot while developing, as all necessary dependencies are handled for you. After installation and ensuring the `docker-compose` command works, you need to: @@ -41,7 +37,7 @@ remove the option altogether to allow all addresses. If you would rather not or are unable to run docker, the following will instruct you on how to install the dependencies natively: -#### Install libolm +#### Install libolm (optional) You can install [libolm](https://gitlab.matrix.org/matrix-org/olm) from source, or alternatively, check your system's package manager. Version `3.0.0` or @@ -83,6 +79,20 @@ Install python dependencies: pip install -e . ``` +This projects uses [Wand](https://docs.wand-py.org) and requires you to install ImageMagick library. + +Debian/Ubuntu: + +``` +sudo apt install libmagickwand-dev +``` + +Arch: + +``` +sudo pacman -S imagemagick +``` + (Optional) If you want to use postgres as a database backend, use the following command to install postgres dependencies alongside those that are necessary: @@ -134,42 +144,21 @@ source env/bin/activate Then simply run the bot with: ``` -my-project-name +nyx-bot ``` -You'll notice that "my-project-name" is scattered throughout the codebase. When +You'll notice that "nyx-bot" is scattered throughout the codebase. When it comes time to modifying the code for your own purposes, you are expected to -replace every instance of "my-project-name" and its variances with your own +replace every instance of "nyx-bot" and its variances with your own project's name. By default, the bot will run with the config file at `./config.yaml`. However, an alternative relative or absolute filepath can be specified after the command: ``` -my-project-name other-config.yaml +nyx-bot other-config.yaml ``` -## Testing the bot works +## Final steps Invite the bot to a room and it should accept the invite and join. - -By default nio-template comes with an `echo` command. Let's test this now. -After the bot has successfully joined the room, try sending the following -in a message: - -``` -!c echo I am a bot! -``` - -The message should be repeated back to you by the bot. - -## Going forwards - -Congratulations! Your bot is up and running. Now you can modify the code, -re-run the bot and see how it behaves. Have fun! - -## Troubleshooting - -If you had any difficulties with this setup process, please [file an -issue](https://github.com/anoadragon453/nio-template/issues]) or come talk -about it in [the matrix room](https://matrix.to/#/#nio-template). diff --git a/docker/Dockerfile b/docker/Dockerfile index 73123db..769bc51 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -60,7 +60,7 @@ RUN apk add --no-cache \ # This speeds up subsequent image builds when the source code is changed RUN mkdir -p /src/nyx_bot COPY nyx_bot/__init__.py /src/nyx_bot/ -COPY README.md my-project-name /src/ +COPY README.md nyx-bot /src/ # Build the dependencies COPY setup.py /src/setup.py @@ -91,11 +91,12 @@ COPY --from=builder /usr/local/lib/libolm* /usr/local/lib/ RUN apk add --no-cache \ libstdc++ \ libpq \ - postgresql-dev + postgresql-dev \ + imagemagick # Specify a volume that holds the config file, SQLite3 database, # and the matrix-nio store VOLUME ["/data"] # Start the bot -ENTRYPOINT ["my-project-name", "/data/config.yaml"] +ENTRYPOINT ["nyx-bot", "/data/config.yaml"] diff --git a/docker/Dockerfile.dev b/docker/Dockerfile.dev index 03397f7..f8b81a5 100644 --- a/docker/Dockerfile.dev +++ b/docker/Dockerfile.dev @@ -49,13 +49,14 @@ RUN apk add --no-cache \ musl-dev \ libpq \ postgresql-dev \ - libstdc++ + libstdc++ \ + imagemagick # Install python runtime modules. We do this before copying the source code # such that these dependencies can be cached RUN mkdir -p /src/nyx_bot COPY nyx_bot/__init__.py /src/nyx_bot/ -COPY README.md my-project-name /src/ +COPY README.md nyx-bot /src/ COPY setup.py /src/setup.py RUN pip install -e "/src/.[postgres]" @@ -68,4 +69,4 @@ COPY *.py /src/ VOLUME ["/data"] # Start the app -ENTRYPOINT ["my-project-name", "/data/config.yaml"] +ENTRYPOINT ["nyx-bot", "/data/config.yaml"] diff --git a/docker/README.md b/docker/README.md index b039e31..74ecdd2 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,6 +1,6 @@ # Docker -The docker image will run my-project-name with a SQLite database and +The docker image will run nyx-bot with a SQLite database and end-to-end encryption dependencies included. For larger deployments, a connection to a Postgres database backend is recommended. @@ -44,7 +44,7 @@ differences: If using postgres, point to your postgres instance instead: ``` - database: "postgres://username:password@postgres/my-project-name?sslmode=disable" + database: "postgres://username:password@postgres/nyx-bot?sslmode=disable" ``` **Note:** a postgres container is defined in `docker-compose.yaml` for your convenience. @@ -80,20 +80,20 @@ docker-compose up -d postgres Start the bot with: ``` -docker-compose up my-project-name +docker-compose up nyx-bot ``` This will run the bot and log the output to the terminal. You can instead run the container detached with the `-d` flag: ``` -docker-compose up -d my-project-name +docker-compose up -d nyx-bot ``` (Logs can later be accessed with the `docker logs` command). This will use the `latest` tag from -[Docker Hub](https://hub.docker.com/somebody/my-project-name). +[Docker Hub](https://hub.docker.com/ShadowRZ/nyx-bot). If you would rather run from the checked out code, you can use: @@ -116,7 +116,7 @@ remove the option altogether to allow all addresses. To update the container, navigate to the bot's `docker` directory and run: ``` -docker-compose pull my-project-name +docker-compose pull nyx-bot ``` Then restart the bot. @@ -124,26 +124,26 @@ Then restart the bot. ## Systemd A systemd service file is provided for your convenience at -[my-project-name.service](my-project-name.service). The service uses +[nyx-bot.service](nyx-bot.service). The service uses `docker-compose` to start and stop the bot. -Copy the file to `/etc/systemd/system/my-project-name.service` and edit to +Copy the file to `/etc/systemd/system/nyx-bot.service` and edit to match your setup. You can then start the bot with: ``` -systemctl start my-project-name +systemctl start nyx-bot ``` and stop it with: ``` -systemctl stop my-project-name +systemctl stop nyx-bot ``` To run the bot on system startup: ``` -systemctl enable my-project-name +systemctl enable nyx-bot ``` ## Building the image @@ -152,5 +152,5 @@ To build a production image from source, use the following `docker build` comman from the repo's root: ``` -docker build -t somebody/my-project-name:latest -f docker/Dockerfile . +docker build -t ShadowRZ/nyx-bot:latest -f docker/Dockerfile . ``` diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index dd1334c..7b153a0 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -8,8 +8,8 @@ volumes: services: # Runs from the latest release - my-project-name: - image: somebody/my-project-name + nyx-bot: + image: ShadowRZ/nyx-bot restart: always volumes: - data_volume:/data diff --git a/docker/my-project-name.service b/docker/my-project-name.service deleted file mode 100644 index daa99d1..0000000 --- a/docker/my-project-name.service +++ /dev/null @@ -1,16 +0,0 @@ -[Unit] -Description=A matrix bot that does amazing things! - -[Service] -Type=simple -User=my-project-name -Group=my-project-name -WorkingDirectory=/path/to/my-project-name/docker -ExecStart=/usr/bin/docker-compose up my-project-name -ExecStop=/usr/bin/docker-compose stop my-project-name -RemainAfterExit=yes -Restart=always -RestartSec=3 - -[Install] -WantedBy=multi-user.target \ No newline at end of file diff --git a/docker/nyx-bot.service b/docker/nyx-bot.service new file mode 100644 index 0000000..eae28b8 --- /dev/null +++ b/docker/nyx-bot.service @@ -0,0 +1,16 @@ +[Unit] +Description=Nyx Bot + +[Service] +Type=simple +User=nyx-bot +Group=nyx-bot +WorkingDirectory=/path/to/nyx-bot/docker +ExecStart=/usr/bin/docker-compose up nyx-bot +ExecStop=/usr/bin/docker-compose stop nyx-bot +RemainAfterExit=yes +Restart=always +RestartSec=3 + +[Install] +WantedBy=multi-user.target diff --git a/nyx_bot/bot_commands.py b/nyx_bot/bot_commands.py index b95d1a4..90ec128 100644 --- a/nyx_bot/bot_commands.py +++ b/nyx_bot/bot_commands.py @@ -254,12 +254,21 @@ Outside of a reply, send the avatar of the command sender.\ topic = self.args[0] if topic == "commands": text = """\ -Available commands: +Only avaliable on a reply: -* `quote`: Make a new quote image. This command must be used on a reply. -* `send_avatar`: Send an avatar. When used in a reply, send the avatar of the person being replied to. Outside of a reply, send the avatar of the command sender. -* `send_as_sticker`: Turn an image into a sticker. This command must be used on a reply. -* `multiquote [count]`: (count is in [2, 6]) Make a new multiquote image. This command must be used on a reply. +* `quote`: Make a new quote image. +* `send_as_sticker`: Turn an image into a sticker. +* `multiquote [count]`: (count is in [2, 6]) Make a new multiquote image. + +Usable anywhere: + +* `archlinuxcn [package]`: Query a package in [archlinuxcn]. +* `emit_statistics`: Show statistics. +* `crazy_thursday`: On Thrusday, print "Crazy Thursday !!". Otherwise print remaining time to next Thursday. + +Others: + +* `send_avatar`: In a reply, send the avatar of the person being replied to. Outside of a reply, send the avatar of the command sender. """ else: text = "Unknown help topic!"