Improved README, added section about Pip package

This commit is contained in:
Casey 2023-05-08 17:57:43 +03:00
parent fb7d5b8e44
commit 3bd0b78122
Signed by: hkc
GPG Key ID: F0F6CFE11CDB0960
2 changed files with 61 additions and 9 deletions

1
.gitignore vendored
View File

@ -1,3 +1,4 @@
dist/
__pycache__ __pycache__
*.py[cow] *.py[cow]
config-*.ini config-*.ini

View File

@ -1,14 +1,29 @@
# mastoposter - easy-to-use mastodon-to-[everything] reposter! # mastoposter - easy-to-use mastodon-to-[everything] reposter
Mastoposter is a simple zero-headache* service that forwards your toots from any Mastoposter is a simple zero-headache* service that forwards your toots from any
Mastodon-compatible Fediverse software (Pleroma also works!) to any of your Mastodon-compatible Fediverse software (Pleroma also works\*\*!) to any of your
other services! For now it supports only Discord webhooks and Telegram, but it other services! For now it supports only Discord webhooks and Telegram, but it
can be easily extended to support pretty much anything! can be easily extended to support pretty much anything!
## Installation ## Installation
### Via pip
Since recently we have package published to pip (thanks to
[@cybertailor@deadinsi.de](https://deadinsi.de/@cybertailor) for adding
pyproject file), so now you can just do the following:
```sh
pip install mastoposter
```
Note that you would still have to clone repository to build a Docker image.
### Old way
You can run it either on your host machine, or inside a Docker container. You can run it either on your host machine, or inside a Docker container.
In any case, you have to clone that repo first in order to do anything: In any case, you have to clone that repo first in order to do anything:
```sh ```sh
git clone https://github.com/hatkidchan/mastoposter && cd mastoposter git clone https://github.com/hatkidchan/mastoposter && cd mastoposter
``` ```
@ -16,11 +31,14 @@ git clone https://github.com/hatkidchan/mastoposter && cd mastoposter
After that, you can either run it in Docker, set up a standalone systemd After that, you can either run it in Docker, set up a standalone systemd
service, or just run it as it is! service, or just run it as it is!
### Docker: ### Docker
```sh ```sh
docker build -t mastoposter . docker build -t mastoposter .
docker run --restart=always -dv /path/to/config.ini:/config.ini:ro --name mastoposter mastoposter docker run -d \
--restart=unless-stopped \
-v /path/to/config.ini:/config.ini:ro \
--name mastoposter mastoposter
``` ```
And you should be good to go And you should be good to go
@ -51,22 +69,33 @@ Before running it though, don't forget to install dependencies from the
Though, that's outside of the scope of that, so I won't cover it here. Though, that's outside of the scope of that, so I won't cover it here.
### Running manually ### Running manually
Just be in the folder with it, have dependencies installed and run: Just be in the folder with it, have dependencies installed and run:
```sh
python3 -m mastoposter config.ini python3 -m mastoposter config.ini
```
## Configuration ## Configuration
Configuration file is just a regular INI file with a couple sections. Configuration file is just a regular INI file with a couple sections.
Configuration wizard is still in progress, but we have a couple examples for
common use-cases. If you have troubles configuring it yourself, you could
either use discussions feature, or ask me on Fedi directly (links on profile).
### [main] ### [main]
Section `main` contains settings of your account (ie, your instance, list ID, Section `main` contains settings of your account (ie, your instance, list ID,
user ID, access token), as well as list of modules to load. user ID, access token), as well as list of modules to load.
#### instance #### instance
This is your instance. It should be written without the `https://` part, so, This is your instance. It should be written without the `https://` part, so,
for example, `mastodon.social`. for example, `mastodon.social`.
#### token #### token
This is your access token. This is your access token.
On Mastodon, you can acquire it by creating an application with the minimum of On Mastodon, you can acquire it by creating an application with the minimum of
@ -78,6 +107,7 @@ tab of the devtools and look for `chats` request. Inside the request headers,
there should be `Authorization: Bearer XXXXXXXXXXX` header. That's your token. there should be `Authorization: Bearer XXXXXXXXXXX` header. That's your token.
#### user #### user
It's still not properly tested, but you could just leave it as `auto` for now. It's still not properly tested, but you could just leave it as `auto` for now.
In case it fails, on Mastodon you can get your user ID by looking at your In case it fails, on Mastodon you can get your user ID by looking at your
@ -88,6 +118,7 @@ On Pleroma you're out of luck again, I don't remember how I got mine. Just hope
that "auto" will work, lol. that "auto" will work, lol.
#### list #### list
That's the main problem of this crossposter: it requires a list to be created That's the main problem of this crossposter: it requires a list to be created
to function properly. Both Pleroma and Mastodon support them, so it shouldn't be to function properly. Both Pleroma and Mastodon support them, so it shouldn't be
a big deal. Just create a list, add yourself into it and copy its ID (it should a big deal. Just create a list, add yourself into it and copy its ID (it should
@ -97,18 +128,22 @@ List is required to filter incoming events. You can't just listen for home
timeline 'cause some events are not guaranteed to be there (boosts at least). timeline 'cause some events are not guaranteed to be there (boosts at least).
#### auto-reconnect #### auto-reconnect
You can set it to either `yes` or `no`. When set to `yes`, it will reconnect You can set it to either `yes` or `no`. When set to `yes`, it will reconnect
on any websocket error, but not on any error related to modules (even if it's a on any websocket error, but not on any error related to modules (even if it's a
connection error!!!) connection error!!!)
#### modules #### modules
More about them later More about them later
#### loglevel #### loglevel
Self-explanatory, logging level. Can be either `DEBUG`, `INFO`, `WARNING` or Self-explanatory, logging level. Can be either `DEBUG`, `INFO`, `WARNING` or
`ERROR`. Defaults to `INFO` `ERROR`. Defaults to `INFO`
### Modules ### Modules
There's two types of modules supported at this point: `telegram` and `discord`. There's two types of modules supported at this point: `telegram` and `discord`.
Both of them are self-explanatory, but we'll go over them real quick. Both of them are self-explanatory, but we'll go over them real quick.
@ -121,6 +156,7 @@ not have the `module/` prefix since it's always there. You can use multiple
modules and separate them using spaces. modules and separate them using spaces.
#### `type = telegram` #### `type = telegram`
Module with that type will work in Telegram mode. Module with that type will work in Telegram mode.
It requires your Bot token to be set in the `token` field, as well as `chat` It requires your Bot token to be set in the `token` field, as well as `chat`
to be set with your chat ID. You can use `@username` if the chat is public. to be set with your chat ID. You can use `@username` if the chat is public.
@ -135,13 +171,14 @@ such as `reblog_or_status` which points to either reblog, or status itself. Or
`name_emojiless` which contains the name without emojis. Or `name` which `name_emojiless` which contains the name without emojis. Or `name` which
contains either `display_name` or `username`, if first one is empty. contains either `display_name` or `username`, if first one is empty.
#### `type = discord` #### `type = discord`
Module for Discord webhooks. The only required parameter (besides the `type`) is Module for Discord webhooks. The only required parameter (besides the `type`) is
`webhook`. It **should** have `wait=true` set. You can also use `thread_id` as a `webhook`. It **should** have `wait=true` set. You can also use `thread_id` as a
GET parameter to that. You also can use filters, nothing special about that. GET parameter to that. You also can use filters, nothing special about that.
### Filters ### Filters
Filters are the most powerful feature of this crossposter. They allow you to... Filters are the most powerful feature of this crossposter. They allow you to...
Filter out where posts should and shouldn't go! It's that easy! Filter out where posts should and shouldn't go! It's that easy!
@ -155,6 +192,7 @@ AND operator. You can also prefix filter name with either `~` or `!` to invert
its behavior. its behavior.
#### `type = boost` #### `type = boost`
Simple filter that passes through posts that are boosted from someone. Simple filter that passes through posts that are boosted from someone.
It also has an optional `list` property where you can specify the list of It also has an optional `list` property where you can specify the list of
@ -166,16 +204,19 @@ trigger that filter. If list is not empty, it will allow only users from that
list. list.
#### `type = mention` #### `type = mention`
This filter is kinda similar to the `boost` one, but works with mentions. This filter is kinda similar to the `boost` one, but works with mentions.
Also has `list` property, yada yada you got the idea, same deal with fnmatch. Also has `list` property, yada yada you got the idea, same deal with fnmatch.
#### `type = spoiler` #### `type = spoiler`
Matches posts with spoilers/content-warnings. Matches posts with spoilers/content-warnings.
Has an optional `regexp` parameter that will allow you to specify regular Has an optional `regexp` parameter that will allow you to specify regular
expression to match your spoiler text. expression to match your spoiler text.
#### `type = content` #### `type = content`
Filter to match post content against either a regular expression, or a list of Filter to match post content against either a regular expression, or a list of
tags. Matching is done on the plaintext version of the post. tags. Matching is done on the plaintext version of the post.
@ -188,12 +229,14 @@ Please note that in case of tags, you should NOT use `#` symbol in front of
them. them.
#### `type = visibility` #### `type = visibility`
Simple filter that just checks for post visibility. Simple filter that just checks for post visibility.
Has a single property `options` that is a space-separated list of allowed Has a single property `options` that is a space-separated list of allowed
visibility levels. Note that `direct` visibility is always ignored so cannot visibility levels. Note that `direct` visibility is always ignored so cannot
be used here. be used here.
#### `type = media` #### `type = media`
Filter that allows only some media types to be posted. Filter that allows only some media types to be posted.
`valid_media` is a space-separated list of media types from Mastodon API `valid_media` is a space-separated list of media types from Mastodon API
@ -207,6 +250,7 @@ opposite: if status has media with that type, filter won't trigger. `only`
allows statuses with either no media, or listed types only. allows statuses with either no media, or listed types only.
#### `type = combined` #### `type = combined`
The most powerful filter 'cause it allows you to combine multiple filters using The most powerful filter 'cause it allows you to combine multiple filters using
different operations. different operations.
@ -221,7 +265,8 @@ some sort.
## Sample configurations ## Sample configurations
### For Telegram: ### For Telegram
```ini ```ini
[main] [main]
modules = tg modules = tg
@ -236,7 +281,8 @@ token = 12345:blahblahblah
chat = 12345 chat = 12345
``` ```
### For Telegram with a separate shitpost channel: ### For Telegram with a separate shitpost channel
```ini ```ini
[main] [main]
modules = tg tg-shitpost modules = tg tg-shitpost
@ -253,7 +299,7 @@ filters = !shitpost
[module/tg-shitpost] [module/tg-shitpost]
type = telegram type = telegram
token = 12345:blahblahblah token = ${module/tg:token}
chat = @shitposting chat = @shitposting
filters = shitpost filters = shitpost
@ -262,3 +308,8 @@ type = content
mode = tag mode = tag
tags = shitpost tags = shitpost
``` ```
## Asterisks
1. Well, most of the time that is.
2. Works only when it has lists support.