Add a SETUP.md file with setup instructions, and link to it from the README
This commit is contained in:
Andrew Morgan
parent
36cf756f04
commit
62111f0ca6
3 changed files with 207 additions and 36 deletions
|
|
@ -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:
|
||||
|
|
|
|||
35
README.md
35
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!
|
||||
|
|
|
|||
176
SETUP.md
Normal file
176
SETUP.md
Normal file
|
|
@ -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).
|
||||
Loading…
Reference in a new issue