Add a SETUP.md file with setup instructions, and link to it from the README

CONTRIBUTING.md

@@ -5,33 +5,9 @@ to help you with contributing.
 
 ## Setting up your development environment
 
-### Using `docker-compose`
+See the
-
+[Install the dependencies section of SETUP.md](SETUP.md#install-the-dependencies)
-It is **recommended** to use Docker Compose to run the bot while
+for help setting up a running environment for the bot.
-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 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:

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
+Any questions? Please ask them in
-[#nio-template:amorgan.xyz](https://matrix.to/#/!vmWBOsOkoOtVHMzZgN:amorgan.xyz?via=amorgan.xyz)!
+[#nio-template:amorgan.xyz](https://matrix.to/#/!vmWBOsOkoOtVHMzZgN:amorgan.xyz?via=amorgan.xyz)
+and we'll help you out!

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).