chat.sr.ht: initial docs

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