add readme, rename binary

2021-08-22 13:01:33 +02:00
parent df197f91b7
commit 4c8fbb413d
3 changed files with 123 additions and 24 deletions
@@ -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, won’t 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