-
-
Notifications
You must be signed in to change notification settings - Fork 407
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
24 changed files
with
659 additions
and
56 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
# Configuration reference | ||
|
||
## Config file | ||
|
||
For configuration you simply need to create a single YAML file named `configuration.yaml`. When you run opsdroid it will look for the file in the following places in order: | ||
|
||
* `./configuration.yaml` | ||
* `~/.opsdroid/configuration.yaml` | ||
* `/etc/opsdroid/configuration.yaml` | ||
|
||
The opsdroid project itself is very simple and requires modules to give it functionality. In your configuration file you must specify the connector, skill and database* modules you wish to use and any options they may require. | ||
|
||
**Connectors** are modules for connecting opsdroid to your specific chat service. **Skills** are modules which define what actions opsdroid should perform based on different chat messages. **Database** modules connect opsdroid to your chosen database and allows skills to store information between messages. | ||
|
||
## Reference | ||
|
||
### `connectors` | ||
|
||
Connector modules which are installed and connect opsdroid to a specific chat service. | ||
|
||
_Config options of the connectors themselves differ between connectors, see the connector documentation for details._ | ||
|
||
```yaml | ||
connectors: | ||
|
||
slack: | ||
token: "mysecretslacktoken" | ||
|
||
# conceptual connector | ||
twitter: | ||
oauth_key: "myoauthkey" | ||
secret_key: "myoauthsecret" | ||
``` | ||
See [module options](#module-options) for installing custom connectors. | ||
### `databases` | ||
|
||
Database modules which connect opsdroid to a persistent data storage service. | ||
|
||
Skills can store data in opsdroid's "memory", this is a dictionary which can be persisted in an external database. | ||
|
||
_Config options of the databases themselves differ between databases, see the database documentation for details._ | ||
|
||
```yaml | ||
databases: | ||
mongo: | ||
host: "mymongohost.mycompany.com" | ||
port: "27017" | ||
database: "opsdroid" | ||
``` | ||
|
||
See [module options](#module-options) for installing custom databases. | ||
|
||
### `logging` | ||
|
||
Set the logging level of opsdroid. | ||
|
||
All python logging levels are available in opsdroid. `logging` can be set to `debug`, `info`, `warning`, `error` and `critical`. | ||
|
||
```yaml | ||
logging: debug | ||
connectors: | ||
shell: | ||
skills: | ||
hello: | ||
seen: | ||
``` | ||
|
||
### `skills` | ||
|
||
Skill modules which add functionality to opsdroid. | ||
|
||
_Config options of the skills themselves differ between skills, see the skill documentation for details._ | ||
|
||
```yaml | ||
skills: | ||
hello: | ||
seen: | ||
``` | ||
|
||
See [module options](#module-options) for installing custom skills. | ||
|
||
## Module options | ||
|
||
All modules are installed from git repositories. By default if no additional options are specified opsdroid will look for the repository at `https://github.com/opsdroid/<moduletype>-<modulename>.git`. | ||
|
||
However if you wish to install a module from a different location you can specify the some more options. | ||
|
||
### `repo` | ||
|
||
A git url to install the module from. | ||
|
||
```yaml | ||
connectors: | ||
slack: | ||
token: "mysecretslacktoken" | ||
mynewconnector: | ||
repo: https://github.com/username/myconnector.git | ||
``` | ||
|
||
### `no-cache` | ||
|
||
Set this to do a fresh git clone of the module whenever you start opsdroid. | ||
|
||
```yaml | ||
databases: | ||
mongodb: | ||
repo: https://github.com/username/mymongofork.git | ||
no-cache: true | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
# Contributing to the project | ||
|
||
Contributing to the opsdroid ecosystem is strongly encouraged. You can do this by creating modules to be used by opsdroid or by contributing to the project itself. | ||
|
||
## Workflow | ||
|
||
All contributors to the project, including [jacobtomlinson](https://github.com/jacobtomlinson), contribute using the following process: | ||
|
||
* Fork the main project to your own account | ||
* Work on your changes on a feature branch | ||
* Create a pull request back to the main project | ||
* Tests and test coverage will be checked automatically | ||
* A project maintainer will review and merge the pull request | ||
|
||
## Developing | ||
|
||
```shell | ||
# clone the repo | ||
git clone https://github.com/opsdroid/opsdroid.git | ||
cd opsdroid | ||
|
||
# install project dependancies | ||
pip install -r requirements.txt | ||
|
||
# run opsdroid | ||
python -m opsdroid | ||
``` | ||
|
||
Running the tests | ||
|
||
```shell | ||
# install test runner | ||
pip install -U tox | ||
|
||
# run tests | ||
tox | ||
``` | ||
|
||
|
||
## Developing in containers | ||
|
||
Developing in containers can be a great way to ensure that opsdroid will run in a clean python environment and that all dependancies are captured. | ||
|
||
```shell | ||
# build the container | ||
docker build -t opsdroid/opsdroid:myfeature . | ||
|
||
# run opsdroid | ||
docker run --rm -ti -v $(pwd):/usr/src/app opsdroid/opsdroid:myfeature | ||
``` | ||
|
||
Running the tests | ||
|
||
```shell | ||
# run tests | ||
docker run --rm -ti -v $(pwd):/usr/src/app opsdroid/opsdroid:myfeature tox | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Creating a connector | ||
|
||
To do... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Creating a database | ||
|
||
To do |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,103 @@ | ||
# Creating skills | ||
|
||
Like all opsdroid modules skills are installed as a git repository. However skills are designed to be simpler than other modules to ensure that it is easy to get started. | ||
|
||
To create a skill you need to create a single python file in your repository with the same name as the skill repository. For example the skill `hello` has a single file called `hello.py`. | ||
|
||
Within this file should be functions which are decorated with an opsdroid skill function to let opsdroid know when to trigger the skill. Let's get started with an example. | ||
|
||
## Hello world | ||
|
||
```python | ||
from opsdroid.skills import match_regex | ||
|
||
@match_regex('hi') | ||
def hello(opsdroid, message): | ||
message.respond('Hey') | ||
``` | ||
|
||
In this example we are importing the `match_regex` decorator from the opsdroid skills library. We are then using it to decorate a simple hello world function. | ||
|
||
The decorator takes a regular expression to match against the message received from the connector. In this case we are checking to see if the message from the user is "hi". | ||
|
||
If the message matches the regular expression then the decorated function is called. As arguments opsdroid will pass a pointer to itself along with a Message object containing information about the message from the user. | ||
|
||
## Message object | ||
|
||
The message object passed to the skill function is an instance of the opsdroid Message class which has the following properties and methods. | ||
|
||
### `text` | ||
|
||
A _string_ containing the message from the user. | ||
|
||
### `user` | ||
|
||
A _string_ containing the username of the user who wrote the message. | ||
|
||
### `room` | ||
|
||
A _string_ containing the name of the room or chat channel the message was sent in. | ||
|
||
### `regex` | ||
|
||
A _[re match object](https://docs.python.org/2/library/re.html#re.MatchObject)_ for the regular expression the message was matched against. | ||
|
||
### `connector` | ||
|
||
A pointer to the opsdroid _connector object_ which receieved the message. | ||
|
||
### `respond(text)` | ||
|
||
A method which responds to the message in the same room using the same connector that it was received. | ||
|
||
## Persisting data | ||
|
||
opsdroid has a memory class which can be used to persist data between different connectors (which run in different process forks) and between restarts of the application. | ||
|
||
The data can be accessed via the `memory` property of the `opsdroid` pointer which is passed to the skill function. The `memory` object has the following methods. | ||
|
||
### `get(key)` | ||
|
||
Returns an object from the memory for the key provided. | ||
|
||
### `put(key, object)` | ||
|
||
Stores the object provided for a specific key. | ||
|
||
### Example | ||
|
||
```python | ||
from opsdroid.skills import match_regex | ||
|
||
@match_regex(r'remember (.*)') | ||
def remember(opsdroid, message): | ||
remember = message.regex.group(1) | ||
opsdroid.memory.put("remember", remember) | ||
message.respond("OK I'll remember that") | ||
|
||
@match_regex(r'remind me') | ||
def remember(opsdroid, message): | ||
message.respond( | ||
opsdroid.memory.get("remember") | ||
) | ||
``` | ||
|
||
In the above example we have defined two skill functions. The first takes whatever the user says after the work "remember" and stores it in the database. | ||
|
||
The second retrieves and prints out that text when the user says "remind me". | ||
|
||
## Setup | ||
|
||
If your skill requires any setup to be done when opsdroid is started you can create a method simple called `setup` which takes a pointer to opsdroid as it's only argument. | ||
|
||
```python | ||
def setup(opsdroid): | ||
# do some setup stuff here | ||
``` | ||
|
||
## Example modules | ||
|
||
See the following official modules for examples: | ||
|
||
* [hello](https://github.com/opsdroid/skill-hello) - A simple hello world skill. | ||
* [seen](https://github.com/opsdroid/skill-seen) - Makes use of opsdroid memory. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
# Getting started | ||
|
||
## Installation | ||
|
||
You can simply install opsdroid using `pip`. | ||
|
||
``` | ||
pip3 install opsdroid | ||
``` | ||
|
||
Or you can use the official docker image. | ||
|
||
``` | ||
docker pull opsdroid/opsdroid:latest | ||
``` | ||
|
||
## Configuration | ||
|
||
For configuration you simply need to create a single YAML file named `configuration.yaml`. When you run opsdroid it will look for the file in the following places in order: | ||
|
||
* `./configuration.yaml` | ||
* `~/.opsdroid/configuration.yaml` | ||
* `/etc/opsdroid/configuration.yaml` | ||
|
||
The opsdroid project itself is very simple and requires modules to give it functionality. In your configuration file you must specify the connector, skill and database* modules you wish to use and any options they may require. | ||
|
||
**Connectors** are modules for connecting opsdroid to your specific chat service. **Skills** are modules which define what actions opsdroid should perform based on different chat messages. **Database** modules connect opsdroid to your chosen database and allows skills to store information between messages. | ||
|
||
For example a simple barebones configuration would look like: | ||
|
||
```yaml | ||
connectors: | ||
shell: | ||
|
||
skills: | ||
hello: | ||
``` | ||
This tells opsdroid to use the [shell connector](https://github.com/opsdroid/connector-shell) and [hello skill](https://github.com/opsdroid/skill-hello) from the official module library. | ||
In opsdroid all modules are git repositories which will be cloned locally the first time they are used. By default if you do not specify a repository opsdroid will look at `https://github.com/opsdroid/<moduletype>-<modulename>.git` for the repository. Therefore in the above configuration the `connector-shell` and `skill-hello` repositories were pulled from the opsdroid organisation on GitHub. | ||
|
||
You are of course encouraged to write your own modules and make them available on GitHub or any other repository host which is accessible by your opsdroid installation. | ||
|
||
A more advanced config would like similar to the following: | ||
|
||
```yaml | ||
connectors: | ||
slack: | ||
token: "mysecretslacktoken" | ||
databases: | ||
mongo: | ||
host: "mymongohost.mycompany.com" | ||
port: "27017" | ||
database: "opsdroid" | ||
skills: | ||
hello: | ||
seen: | ||
myawesomeskill: | ||
repo: "https://github.com/username/myawesomeskill.git" | ||
``` | ||
|
||
In this configuration we are using the [slack connector](https://github.com/opsdroid/connector-slack) with a slack [auth token](https://api.slack.com/tokens) supplied, a [mongo database](https://github.com/opsdroid/database-mongo) connection for persisting data, `hello` and `seen` skills from the official repos and finally a custom skill hosted on GitHub. | ||
|
||
Configuration options such as the `token` in the slack connector or the `host`, `port` and `database` options in the mongo database are specific to those modules. Ensure you check each module's required configuration items before you use them. | ||
|
||
## Running | ||
|
||
If you installed opsdroid using `pip` and have created your `configuration.yaml` file in the correct place you can simple start it by running: | ||
|
||
``` | ||
opsdroid | ||
``` | ||
|
||
If you are using the opsdroid docker image then ensure you add your configuration as a volume and run the container. | ||
|
||
``` | ||
docker run --rm -v /path/to/configuration.yaml:/etc/configuration.yaml:ro opsdroid/opsdroid:latest | ||
``` | ||
------- | ||
_\* databases are optional, however bot memory will not persist between different connectors or system reboots without one_ |
Oops, something went wrong.