Fedi Groups

How it works

This is an approximation of groups you can use right now with existing fedi software that implements the Mastodon client API.

A group is a regular user account controlled by a "bot" service that runs on a Linux server (e.g. a Rpi in your closet). To join a group, simply follow the group user. To post into the group, tag the group user in a top-level post (not a reply), or use /b in a reply to share the parent post to the group. The group will reblog shared posts to its members.

Groups implement moderation (banning users and instances, member-only mode with user whitelist). This is controlled by slash commands, see below.

Group admins can issue group announcements that are posted poublicly by the group user, such as when there is a planned maintenance. The group will attempt to catch up with posts missed during the outage.

Advantages of emulated groups

Unlike some other attempts at group implementation (namely gup.pe or the mythical WIP Pleroma Groups), this works with current Pleroma and Mastodon. There's no need for interoperability in different server implementations, since it uses existing follow/mention/reblog features that are already cross-compatible. Mastodon users can join a group running on Pleroma and vice-versa.

Groups probably can't be hosted on Honk and Misskey, but their users can use groups hosted elsewhere just fine.

Usage

Building

Install the rust toolchain using rustup: 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

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.
Run the group service with fedigroups -a mygroup@groups.social (your account's handle) to authenticate.
Make sure you auth as the correct user!
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.

{
  "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.

An example systemd service file is included in the repository as well. Make sure to set up the system user/group and file permissions according to your needs.

Commands

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.

Posts with commands won’t be boosted by the group actor.

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
/ping - ping the group service to check it's running, it will reply in a DM

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

4.8 KiB Raw Blame History