diff options
Diffstat (limited to 'chat.sr.ht')
| -rw-r--r-- | chat.sr.ht/bouncer-usage.md | 80 | ||||
| -rw-r--r-- | chat.sr.ht/index.md | 55 | ||||
| -rw-r--r-- | chat.sr.ht/quickstart.md | 33 |
3 files changed, 168 insertions, 0 deletions
diff --git a/chat.sr.ht/bouncer-usage.md b/chat.sr.ht/bouncer-usage.md new file mode 100644 index 0000000..33ebf6d --- /dev/null +++ b/chat.sr.ht/bouncer-usage.md @@ -0,0 +1,80 @@ +# Using the chat.sr.ht bouncer + +For full details, refer to the [soju(1)](https://soju.im/doc/soju.1.html) man +page. Information about common use-cases is provided here. + +## Connecting with a third-party IRC client + +<!-- Note: update chat.sr.ht/quickstart.md if changing this --> + +To connect with a third-party IRC client, you will need to generate an OAuth 2.0 +personal access token to use as your server password. Visit [the personal access +token issuance page](https://meta.sr.ht/oauth2/personal-token) and set the +grant string to "meta.sr.ht/PROFILE:RO", adding an optional comment, and leaving +the other fields unchanged. + +**Hostname**: chat.sr.ht +**Port**: 6697 +**SSL/TLS**: Yes +**SASL**: Yes +**Username**: *Your sourcehut username* +**Password**: *Your personal access token* + +If you intend to use multiple clients, it is recommended that you append +"@*clientname*" to your username, using an arbitrary unique string to identify +each client. If your IRC client does not support soju's +"soju.im/bouncer-networks" extension (check if [a plugin is available][config]), +you may want to configure separate connections for each network by using the +username format `username/network-name@client-name`. + +See [client-specific configuration][config] for recommended configuration steps +specific to your preferred IRC client. + +[config]: #client-specific-configuration + +## Managing your IRC networks + +The webchat at [chat.sr.ht](https://chat.sr.ht) provides a UI for managing your +bouncer networks. Third-party clients with soju support may detect the bouncer +and offer similar functionality. If not, you can also message BouncerServ to +configure soju. Use `/msg BouncerServ help` for a full list of supported +commands. + +To add a new IRC network via BouncerServ: + +``` +/msg BouncerServ network create -addr <hostname> [options...] +``` + +See [soju(1)](https://soju.im/doc/soju.1.html#IRC_SERVICE) for details on the +supported options. + +## Detaching from channels + +You can instruct the bouncer to "detach" from a channel. This causes it to be +hidden from your channel list, but to leave your connection to the channel +active. If you're mentioned by a user in this channel, you will receive +notifications for it, and if you re-join later, you will be able to view logs of +discussions which took place in your absence. + +To detach from a channel, use the `/part detach` command, or `/msg BouncerServ +channel update <name> -detached=<true|false>`. + +## Client-specific configuration + +Various configuration recommendations for third-party IRC clients. + +### Weechat + +The [soju.py][soju.py] user script enables you to configure one connection to +soju, then automatically connect to any networks you have configured on the +bouncer. + +[soju.py]: https://weechat.org/scripts/source/soju.py.html/ + +``` +/script install soju.py +/script load soju.py +/script autoload soju.py +/server add .bouncer chat.sr.ht/6697 -ssl -autoconnect -username=<your sourcehut username> -password=<oauth token> +``` diff --git a/chat.sr.ht/index.md b/chat.sr.ht/index.md new file mode 100644 index 0000000..9df4021 --- /dev/null +++ b/chat.sr.ht/index.md @@ -0,0 +1,55 @@ +# chat.sr.ht + +chat.sr.ht provides real-time chat services to sourcehut users based on the +Internet Relay Chat ([IRC][0]) protocol. In technical terms, chat.sr.ht +essentially provides a hosted IRC bouncer for paid users, and a web gateway for +other users. + +**NOTICE**: chat.sr.ht is currently in a closed beta. Reach out to emersion on +libera.chat for details. + +SourceHut does not operate an IRC network. We recommend [Libera Chat][1], an +independently operated, third-party network, which chat.sr.ht is configured to +use by default. Please review the Libera Chat [Network policies][2] for details +on appropriate network usage. + +[0]: https://en.wikipedia.org/wiki/Internet_Relay_Chat +[1]: https://libera.chat +[2]: https://libera.chat/policies + +## chat.sr.ht documentation + +To start using chat.sr.ht, simply visit [chat.sr.ht](https://chat.sr.ht) in your +web browser and log in with your SourceHut credentials. Read the instructions +on-screen to get started. + +We have a few additional guides for different audiences: + +- [Quick-start for experienced IRC users](/chat.sr.ht/quickstart.md) +- [Using the IRC bouncer](/chat.sr.ht/bouncer-usage.md) +- [Setting up an IRC channel for your project](#TODO) +- [Writing an IRC bot](#TODO) +- [Information for network operators](#TODO) + +## chat.sr.ht software + +chat.sr.ht is based on the [soju][3] IRC bouncer and the [gamja][4] webchat +client. Our downstream patches, if any, are kept in the "srht" branch of each. + +[3]: https://soju.im/ +[4]: https://sr.ht/~emersion/gamja/ + +## Official IRC channels and support + +SourceHut operates a number of official IRC channels on libera.chat where you +can get support for sr.ht issues or socialize with other SourceHut users. You +can join them with the `/join <channel>` command. + +- #sr.ht: on-topic sourcehut support and development channel, including for + technical issues related to chat.sr.ht's webchat and bouncer service +- #sr.ht.watercooler: off-topic channel for discussing sourcehut-adjacent topics + with the sourcehut community +- #sr.ht.ops: read-only technical operations & monitoring channel +- #liberachat: official Libera network support, for issues with channel + management, NickServ account maintenance, and moderation and spam concerns. + This channel is not officially affiliated with SourceHut. diff --git a/chat.sr.ht/quickstart.md b/chat.sr.ht/quickstart.md new file mode 100644 index 0000000..8cab29f --- /dev/null +++ b/chat.sr.ht/quickstart.md @@ -0,0 +1,33 @@ +# chat.sr.ht quick-start for experienced IRC users + +The webchat is available at [chat.sr.ht](https://chat.sr.ht) and requires no +configuration to use. It will automatically connect you to your bouncer account. + +You can also connect directly to the bouncer using your own IRC client. + +<!-- Note: update chat.sr.ht/bouncer-usage.md if changing this --> + +To connect with a third-party IRC client, you will need to generate an OAuth 2.0 +personal access token to use as your server password. Visit [the personal access +token issuance page](https://meta.sr.ht/oauth2/personal-token) and set the +grant string to "meta.sr.ht/PROFILE:RO", adding an optional comment, and leaving +the other fields unchanged. + +**Hostname**: chat.sr.ht +**Port**: 6697 +**SSL/TLS**: Yes +**SASL**: Yes +**Username**: *Your sourcehut username* +**Password**: *Your personal access token* + +If you intend to use multiple clients, it is recommended that you append +"@*clientname*" to your username, using an arbitrary unique string to identify +each client. If your IRC client does not support soju's +"soju.im/bouncer-networks" extension (check if [a plugin is available][config]), +you may want to configure separate connections for each network by using the +username format `username/network-name@client-name`. + +See [client-specific configuration][config] for recommended configuration steps +specific to your preferred IRC client. + +[config]: /chat.sr.ht/bouncer-usage.md#client-specific-configuration |