@ -14,7 +14,7 @@ Unlike some other attempts at group implementation (namely gup.pe or the mythica
Groups probably can't be hosted on Honk and Misskey, but their users can use groups hosted elsewhere just fine.
## Usage
## Setup
### Building
@ -37,6 +37,8 @@ The program now ends. The credentials are saved in a file `groups.json`.
You can repeat this for any number of groups.
In case you need to re-authenticate an existing group, do the same but use `-A` instead of `-a`.
### Editing config
**Do not edit the config while the group service is running, it will overwrite your changes!**
@ -57,22 +59,27 @@ The file format is quite self-explanatory.
"redirect": "urn:ietf:wg:oauth:2.0:oob",
"token": "..."
},
"group_tags": [
"grouptest"
],
"admin_users": [
"admin@myserver.xyz"
],
"member_only": false,
"member_users": [],
"banned_users": [],
"member_only": false,
"banned_servers": [
"bad-stuff-here.cc"
],
"last_notif_ts": 1629626621000
"last_notif_ts": 1630011219000,
"last_status_ts": 1630011362000
}
}
}
```
- `member_users` - used if `member_only` is true, then only members and admins can post to the group
- `group_tags` - group hashtags (without the `#`). The group reblogs anything with these hashtags if the author is a member.
- `member_users` - group members, used to track whose hashtags should be reblogged; in member-only groups, this is also a user whitelist.
- `banned_users` - can't post or interact with the group service
- `banned_servers` - work like an instance block
@ -82,33 +89,66 @@ To run the group service, simply run it with no arguments. It will read what to
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.
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. You can use targets in the included `Makefile` to manage the systemd service and look at logs.
## Group usage
### 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.
Replies keep the same visibility level as the post with the command.
**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
Posts with commands, mentioning the group, won’t be boosted.
### Membership
When a user follows a group, the group follows them back and marks them internally as a member. (In member-only groups, a group admin must initiate the second part).
Admin can add or remove group members using the `/add` and `/remove` commands. Users can use `/join` and `/leave`.
Members can use `/join` to make the group re-follow them, for example when the follow somehow stopped working.
**For member-only groups**
### Group mentions
Any user (member in member-only groups) can post to the group by mentioning the group user. The post is then reblogged.
### Group hashtags
Admins can add hashtags to the group config (`/add #hashtag`, remove the same way: `/remove #hashtag`).
When a *group member* posts one of the group hashtags, the group will reblog it. This is a nicer way to share posts, you don't have to mention the group user at all.
For group hashtags to work, the group user must follow all its members; otherwise the posts might not federate to the group's server.
### List of commands
*Note on command arguments:*
- When a command wants user handle as an argument, use the e-mail form, e.g. piggo@piggo.space, to avoid mentioning the user.
- Local users can be specified without the domain part, but the first `@` is then needed.
- When specifying a server (for server ban commands), the name must contain at least one dot.
- Hashtags are specified in their full form with a hash.
**Basic commands**
- `/help` - show help
- `/ignore`, `/i` - make the group completely ignore the post
- `/members`, `/who` - show group members / admins
- `/tags` - show group hashtags
- `/boost`, `/b` - boost the replied-to post into the group
- `/ping` - ping the group service to check it's running, it will reply
- `/join` - join the group
- `/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.
- `/announce x` - make a public announcement from the rest of the status. Note: this does not preserve any formatting!
- `/ban x` - ban a user or a server from the group
- `/unban x` - lift a ban
- `/op, /admin user` - grant admin rights to the group
- `/deop, /deadmin user` - revoke admin rights
- `/op user`, `/admin user` - grant admin rights to the group
- `/deop user`, `/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
- `/kick user, /remove user` - kick a member
- `/add #hashtag` - add a hasgtag to the group
- `/remove #hashtag` - remove a hasgtag from the group
