Pingbot/README.md

# Pingbot

Pingbot monitors a Mastodon account, and will ping one or more other accounts any time
that account gets a notification. This is useful for monitoring an admin account that
may not be logged in all the time, or for checking in on an old account after you've
made a new one.

**You cannot monitor an account you can't log into. This is deliberate and will not be changed.**

## Setup

Pingbot requires the `ananas` package. You can install it with pip:

`pip3 install ananas`

Note that the version of ananas that's currently available on pip (as of 4/28/22) is
*not* compatible with Python 3.10. There's already a PR in to fix that so we just 
have to wait for PyPI to catch up.

You can either download `pingbot.py` and `sample-config.cfg` directly, or you can go to
the command line on the server you want to run Pingbot on and run 

`git clone https://git.noelle.codes/noelle/Pingbot.git`

This will create a new directory called `Pingbot` that contains the repository's files.
You'll run `ananas` (see below) from there.

**In the Mastodon web interface on the account you want to monitor**, open Preferences, 
then Development, and click the New Application button at the upper right.

You'll need to give your application a name; this can be pretty much anything you want.
Leave "Application website" blank, and leave "Redirect URI" alone.

You can leave Scopes alone; all Pingbot does is check your notifications and send you
DMs. However, if you want to limit Pingbot's access for security, it **must** have 
`read:notifications` and `write:statuses` in order to do its job.

Click the Submit button at the bottom, and you'll see "Application successfully created",
as well as your new application in the list below. Click the name you chose (it should be
blue), and this will bring up a screen that shows you the **client key**, **client secret**,
and **access token**.

In Pingbot's directory, copy `sample-config.cfg` to `config.cfg`, and then open it for
editing. You'll need a separate header in the config file, enclosed by [brackets], for
each bot you want to run in the same directory. The sample configuration file includes
a [pingbot] header for you, as well as a [DEFAULT] header for settings that apply to
every bot in the directory. You should place most of your information under the 
[pingbot] header; the configuration file includes instructions on how to do this.
(Note that what the Mastodon web interface calls a "Client key", the config file
calls a `client_id`.)

In the configuration file, every username you include should *not* have an @ before it
(e.g. `noelle@elekk.xyz`, not `@noelle@elekk.xyz`).

Once all your information is in the configuration file, save it, and then run

`ananas config.cfg`

in a terminal window and your bot will start up and begin listening! In Linux, you can
run your bot in the background by adding an & to the end:

`ananas config.cfg &`

Or you can use a window manager like `tmux` or `screen`, which will let you keep the
bot running on a server without you havnig to be logged in.

## Making configuration changes

If you want to change Pingbot's settings, you'll need to stop and restart the bot. 
Make sure you stop the bot *before* you make changes; Pingbot saves its configuration
when it shuts down, and might overwrite your changes.

## I need help!

You can contact me at [my Mastodon account](https://elekk.xyz/@noelle) and
I'll do my best to help you out. :)

## TODO

* On startup, make Pingbot get permission from all accounts it wants to notify (and store that permission so it doesn't ask multiple times)
* Make Pingbot optionally not respond to replies from accounts in its notify list
* Internationalization