add readme, rename binary

This commit is contained in:
Ondřej Hruška 2021-08-22 13:01:33 +02:00
parent df197f91b7
commit 4c8fbb413d
No known key found for this signature in database
GPG key ID: 2C5FD5035250423D
3 changed files with 123 additions and 24 deletions

46
Cargo.lock generated
View file

@ -326,6 +326,29 @@ version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e88a8acf291dafb59c2d96e8f59828f3838bb1a70398823ade51a84de6a6deed"
[[package]]
name = "fedigroups"
version = "0.1.0"
dependencies = [
"anyhow",
"clap",
"elefren",
"env_logger",
"futures 0.3.16",
"log 0.4.14",
"native-tls",
"once_cell",
"regex",
"serde",
"serde_json",
"smart-default",
"thiserror",
"tokio",
"tokio-stream",
"voca_rs",
"websocket",
]
[[package]]
name = "fnv"
version = "1.0.6"
@ -520,29 +543,6 @@ dependencies = [
"wasi 0.10.2+wasi-snapshot-preview1",
]
[[package]]
name = "group"
version = "0.1.0"
dependencies = [
"anyhow",
"clap",
"elefren",
"env_logger",
"futures 0.3.16",
"log 0.4.14",
"native-tls",
"once_cell",
"regex",
"serde",
"serde_json",
"smart-default",
"thiserror",
"tokio",
"tokio-stream",
"voca_rs",
"websocket",
]
[[package]]
name = "h2"
version = "0.3.3"

View file

@ -1,5 +1,5 @@
[package]
name = "group"
name = "fedigroups"
version = "0.1.0"
authors = ["Ondřej Hruška <ondra@ondrovo.com>"]
edition = "2018"

99
README.md Normal file
View file

@ -0,0 +1,99 @@
# Groups for Pleroma!!!
and Mastodon or anything with the Mastodon API.
## Usage
### Building
Install the rust toolchain using `rustup`: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install)
Rust 1.54+ is recommended.
Build with `cargo build`, or optimized: `cargo build --release`. The binary is placed in the `target/debug` or `target/release` directory.
You can also run the program using Cargo, that is handy for development: `cargo run`. When passing command line flags, use `--`: `cargo run -- -i my@group.xyz`.
### Setting up a group account
1. Create the group's account all nice like you want it. Pleroma and Mastodon should work, others may work too but you're on your own.
2. Run the group service with `fedigroups -a mygroup@groups.social` (your account's handle) to authenticate.
3. **Make sure you auth as the correct user!**
4. Paste the Oauth2 token you got into the terminal, hit enter.
The program now ends. The credentials are saved in a file `groups.json`.
You can repeat this for any number of groups.
### Editing config
**Do not edit the config while the group service is running, it will overwrite your changes!**
The JSON file is easily editable, you can e.g. add yourself as an admin (use the e-mail format, e.g. `piggo@piggo.space`).
The file format is quite self-explanatory.
```json
{
"groups": {
"group@myserver.xyz": {
"enabled": true,
"acct": "group@myserver.xyz",
"appdata": {
"base": "https://myserver.xyz",
"client_id": "...",
"client_secret": "...",
"redirect": "urn:ietf:wg:oauth:2.0:oob",
"token": "..."
},
"admin_users": [
"admin@myserver.xyz"
],
"member_users": [],
"banned_users": [],
"member_only": false,
"banned_servers": [
"bad-stuff-here.cc"
],
"last_notif_ts": 1629626621000
}
}
}
```
- `member_users` - used if `member_only` is true, then only members and admins can post to the group
- `banned_users` - can't post or interact with the group service
- `banned_servers` - work like an instance block
### Running
To run the group service, simply run it with no arguments. It will read what to do from `groups.json`.
Note that the file must be writable, it is updated at run-time.
### Commands
To share an original post, mention the group user.
Posts with commands, and replies, wont be shared.
Commands are simple text lines you use when mentioning the group user. DMs work well for this.
One post can contain multiple commands; the replies will be batched to one response.
**Basic commands**
- `/ignore, /i` - make the group completely ignore the post
- `/members, /who` - show group members / admins
- `/boost, /b` - boost the replied-to post into the group
**For member-only groups**
- `/leave` - leave the group
**For admins**
- `/announce x` - make a public announcement from the rest of the status
- `/ban x` - ban a user or a server. Note that this is only on the service level, the account won't be blocked or muted.
- `/unban x` - lift a ban
- `/op, /admin user` - grant admin rights to the group
- `/deop, /deadmin user` - revoke admin rights
- `/opengroup` - make member-only
- `/closegroup` - make public-access
**For admins of private groups**
- `/add user` - add a member (use e-mail style address)
- `/kick, /remove user` - kick a member