diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 473a69f..bb7d12b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,33 +5,9 @@ to help you with contributing. ## Setting up your development environment -### Using `docker-compose` - -It is **recommended** to 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: - -1. Create a data directory and config file by following the - [docker setup instructions](docker#setup). - -2. Create a docker volume pointing to that directory: - - ``` - docker volume create \ - --opt type=none \ - --opt o=bind \ - --opt device="/path/to/data/dir" data_volume - ``` - -Run `docker/start-dev.sh` to start the bot. - -**Note:** If you are trying to connect to a Synapse instance running on the -host, you need to allow the IP address of the docker container to connect. This -is controlled by `bind_addresses` in the `listeners` section of Synapse's -config. If present, either add the docker internal IP address to the list, or -remove the option altogether to allow all addresses. - -### Running natively +See the +[Install the dependencies section of SETUP.md](SETUP.md#install-the-dependencies) +for help setting up a running environment for the bot. If you would rather not or are unable to run docker, the following instructions will explain how to install the project dependencies natively. @@ -85,7 +61,7 @@ command to install postgres dependencies alongside those that are necessary: pip install ".[postgres]" ``` -## Development dependencies +### Development dependencies There are some python dependencies that are required for linting/testing etc. You can install them with: diff --git a/README.md b/README.md index 01ca401..66a49d0 100644 --- a/README.md +++ b/README.md @@ -5,24 +5,42 @@ A template for creating bots with 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/matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot -) - A matrix bot to remind you about things * [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 -* [alturiak/nio-smith](https://github.com/alturiak/nio-smith) - A modular bot for @matrix-org that can be dynamically -extended by plugins -* [gracchus163/hopeless](https://github.com/gracchus163/hopeless) - COREbot for the Hope2020 conference Matrix server Want your project listed here? [Edit this -doc!](https://github.com/anoadragon453/nio-template/edit/master/README.md) +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. ## Project structure +*A reference of each file included in the template repository, its purpose and +what it does.* + The majority of the code is kept inside of the `my_project_name` 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. @@ -132,5 +150,6 @@ defined for when a error is found while the config file is being processed. ## Questions? -Any questions? Ask in -[#nio-template:amorgan.xyz](https://matrix.to/#/!vmWBOsOkoOtVHMzZgN:amorgan.xyz?via=amorgan.xyz)! +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! diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..6dbe3bf --- /dev/null +++ b/SETUP.md @@ -0,0 +1,176 @@ +# Setup + +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. For guidance on how +to get started on transforming the codebase into your own, personalised +chatbot, see [GETTING_STARTED.md](GETTING_STARTED.md). + +## 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 +developing, as all necessary dependencies are handled for you. After +installation and ensuring the `docker-compose` command works, you need to: + +1. Create a data directory and config file by following the + [docker setup instructions](docker#setup). + +2. Create a docker volume pointing to that directory: + + ``` + docker volume create \ + --opt type=none \ + --opt o=bind \ + --opt device="/path/to/data/dir" data_volume + ``` + +Run `docker/start-dev.sh` to start the bot. + +**Note:** If you are trying to connect to a Synapse instance running on the +host, you need to allow the IP address of the docker container to connect. This +is controlled by `bind_addresses` in the `listeners` section of Synapse's +config. If present, either add the docker internal IP address to the list, or +remove the option altogether to allow all addresses. + +### Running natively + +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 + +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 +greater is required. + +**(Optional) postgres development headers** + +By default, the bot uses SQLite as its storage backend. This is fine for a few +hundred users, but if you plan to support a much higher volume of requests, you +may consider using Postgres as a database backend instead. + +If you want to use postgres as a database backend, you'll need to install +postgres development headers: + +Debian/Ubuntu: + +``` +sudo apt install libpq-dev libpq5 +``` + +Arch: + +``` +sudo pacman -S postgresql-libs +``` + +#### Install Python dependencies + +Create and activate a Python 3 virtual environment: + +``` +virtualenv -p python3 env +source env/bin/activate +``` + +Install python dependencies: + +``` +pip install -e . +``` + +(Optional) If you want to use postgres as a database backend, use the following +command to install postgres dependencies alongside those that are necessary: + +``` +pip install -e ".[postgres]" +``` + +## Configuration + +Copy the sample configuration file to a new `config.yaml` file. + +``` +cp sample.config.yaml config.yaml +``` + +Edit the config file. The `matrix` section must be modified at least. + +#### (Optional) Set up a Postgres database + +Create a postgres user and database for matrix-reminder-bot: + +``` +sudo -u postgresql psql createuser nio-template -W # prompts for a password +sudo -u postgresql psql createdb -O nio-template nio-template +``` + +Edit the `storage.database` config option, replacing the `sqlite://...` string with `postgres://...`. The syntax is: + +``` +database: "postgres://username:password@localhost/dbname?sslmode=disable" +``` + +See also the comments in `sample.config.yaml`. + +## Running + +### Docker + +Refer to the docker [run instructions](docker/README.md#running). + +### Native installation + +Make sure to source your python environment if you haven't already: + +``` +source env/bin/activate +``` + +Then simply run the bot with: + +``` +my-project-name +``` + +You'll notice that "my-project-name" 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 +project's name. Details on doing so are described in +[GETTING_STARTED.md](GETTING_STARTED.md). + +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 +``` + +## Testing the bot works + +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).