# Rollbot

## Build

`docker build -t rollbot3:latest .`

## Deploy

`docker run -p6070:6070 --name rollbot3-instance -d rollbot3`

## Local Run w/o Docker

`cd` into `src/` and run
`ROLLBOT_CFG_DIR=../config python3 app.py`

Note this requires at least Python 3.7.1

## Development/Contributing


### First Time Set-Up
If you are developing this project, start by cloning this repository and creating a new branch,
replacing `my-awesome-branch` with your chosen branch name in the following

```bash
git clone ssh://git@kirkleon.ddns.net:10022/kirkleon/rollbot3.git
cd rollbot3/
git checkout -b feature/my-awesome-branch
```

Next, open GroupMe through your preferred application, and create a new chat containing just
yourself. This will be your testing chat, where your local copy of rollbot will post messages.
Future plans for the project include a simpler local testing environment, but integrating with
GroupMe is an important testing step regardless, and so it is reasonable to do it now anyway.

Next, create a `secrets.toml` file. Do **NOT** commit this file! It is by default added to `.gitignore`
for you, but you should always take care you are not accidentally sharing this file.

```bash
cp config/secrets.toml.template config/secrets.toml
```

Open the new `secrets.toml` file in your preferred editor, and then navigate to the GroupMe
[Bots](https://dev.groupme.com/bots) page. In the upper right, you should see a button that says
`Access Token`. Click this, and copy the token into your `secrets.toml`, setting it as the value
for `api-key`. Then, on the bots page, create a new bot. For this bot's group, select the new
chat you made above. Name can be whatever you like, and you can leave the other fields blank.
Click submit, and retrieve your `Bot ID` and `Group ID` from the bots page. Put these in your
`secrets.toml` under the `bots` section, with your `Group ID` serving as the key and the `Bot ID`
serving as the value (which must be in quotes).

For example, if your API key is `123`, your bot ID is `456`, and your group ID is `789`, your
`secrets.toml` needs to start with the following

```toml
api_key = "123"

[bots]
789 = "456"
```

That's it for secrets! Save the file and move on to deciding if you want to do your local development
with or without `docker`.

### Developing w/o Docker

If you have a Python 3.7.1 environment with `pip` available, you can install dependencies as follows

```bash
pip install -r requirements.txt
```

If your plugin or extension adds new dependencies, remember to include them in this `requirements.txt`.

Then, move to the `src/` directory and use the above command to start the local `Flask` server on
port `6070`.

```bash
ROLLBOT_CFG_DIR=../config python3 app.py
```

Use `Ctrl-C` to kill this server. Your development loop will probably look something like, modify
your plugin, start the server, test it, kill the server, repeat.

### Developing w/ Docker

If you do not have Python 3.7.1 (or later) available, or want to develop using docker locally, you
can make use of the `rollbot-docker.sh` script. You will need to run this as `root` (preferably with
`sudo`), or as some user capable of using docker. If you are not running this script as `root`, and
instead have a different local docker user, you will need to `export FORCE_NOROOT=*` before running
the script.

You can run `./rollbot-docker.sh help` to see a full list of options. The most useful are `run` and
`clean`. To build the `rollbot3:latest` image and deploy it to a docker container called
`rollbot3-instance` on your local machine, simply run

```bash
./rollbot-docker.sh run
```

This will also blow away any existing container called `rollbot3-instance` before building the new
image and container. If you would just like to kill and remove existing containers with that name,
without starting a new one, you can run

```bash
./rollbot-docker.sh clean
```

In general, your development loop will probably look something like, modify your plugin, run
`./rollbot-docker.sh run`, and repeat. When you are all done, you can use `./rollbot-docker.sh clean`
to remove the lingering container on your system.

### POSTing to Local Server

Once you have a local server up on `http://localhost:6070/rollbot`, point your REST client of choice
(my personal recommendation is [Insomnia](https://insomnia.rest/)) at that address. Creat a new `POST`
request, of `JSON` type (that is, your `Content-Type` should be `application/json`). Then, set the body
of this `POST` to be

```json
{
  "text": "!echo Hello",
  "group_id": "your-group-id",
  "attachments": [],
  "avatar_url": "https://i.groupme.com/123456789",
  "created_at": 1302623328,
  "id": "1234567890",
  "name": "Insomnia",
  "sender_id": "1",
  "sender_type": "user",
  "source_guid": "GUID",
  "system": false,
  "user_id": "1234567890"
}
```

The first two options, `text` and `group_id` will need to be modified. Set the value of `group_id` to
the group ID you found and put into your `secrets.toml` above. Then, click run! Or however your REST
client sends the request. If you have everything set up correctly, your phone should buzz and you
should receive a message in your bot testing chat you set up before, from the chatbot you added to it,
responding to a `!echo Hello` command. Now, change the value of `text` in the body of your request to
be whatever message you would like to simulate sending, and you should be able to get the hang of how
you can test your local instance of rollbot.

### Writing a Plugin

The quickstart for creating a new plugin is to determine a name for the plugin, say, `my_cool_plugin`,
and run

```bash
./mkplugin my_cool_plugin
```

This will end by printing something like

```
Action required: Insert the following line into the [plugins] section of config/config.toml to activate my_cool_plugin
my_cool_plugin = [ "my_cool_plugin"]
```

Do as it says and open `config/config.toml` and add the printed line to the `[plugins]` map.

This script will also generate a file at `src/plugins/my_cool_plugin.py` containing

```python
from command_system import as_plugin, RollbotResponse


@as_plugin("my_cool_plugin")
def my_cool_plugin(db, msg):
    return RollbotResponse(msg, txt="My first plugin!")
```

This is the most basic possible rollbot plugin, which will simply respond with `My first plugin!`
when it receives a message starting with `!my_cool_plugin`. You can modify the argument to `as_plugin`
to change the plugin's command word, which must be unique within the application.

Further docs to come! Good luck!

### Contributing Your Plugin

Once you are confident your plugin is functional, push your code to remote with the following, again
replacing `my-awesome-branch` with your chosen branch name.

```bash
git push -u origin feature/my-awesome-branch
```

Then, open a [Pull Request](https://kirkleon.ddns.net/gogs/kirkleon/rollbot3/pulls), shoot me a message,
and I'll take it from there!