From 47160e9e06ede6ba19d8704132d225d6ecc1645d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timo=20K=C3=B6sters?= <timo@koesters.xyz>
Date: Sat, 22 May 2021 13:39:31 +0200
Subject: [PATCH] docs: APPSERVICES setup guide

---
 APPSERVICES.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 DEPLOY.md      |  2 ++
 README.md      |  4 ++++
 3 files changed, 54 insertions(+)
 create mode 100644 APPSERVICES.md

diff --git a/APPSERVICES.md b/APPSERVICES.md
new file mode 100644
index 00000000..a84f1d26
--- /dev/null
+++ b/APPSERVICES.md
@@ -0,0 +1,48 @@
+# Setting up Appservices
+
+## Getting help
+
+If you run into any problems while setting up an Appservice, write an email to `timo@koesters.xyz`, ask us in `#conduit:matrix.org` or [open an issue on GitLab](https://gitlab.com/famedly/conduit/-/issues/new).
+
+## Tested appservices
+
+Here are some appservices we tested and that work with Conduit:
+- matrix-appservice-discord
+- mautrix-hangouts
+- mautrix-telegram
+
+## Set up the appservice
+
+Follow whatever instructions are given by the appservice. This usually includes
+downloading, changing its config (setting domain, homeserver url, port etc.)
+and later starting it.
+
+At some point the appservice guide should ask you to add a registration yaml
+file to the homeserver. In Synapse you would do this by adding the path to the
+homeserver.yaml, but in Conduit you can do this from within Matrix:
+
+First, go into the #admins room of your homeserver. The first person that
+registered on the homeserver automatically joins it. Then send a message into
+the room like this:
+
+    @conduit:your.server.name: register_appservice
+    ```
+    paste
+    the
+    contents
+    of
+    the
+    yaml
+    registration
+    here
+    ```
+
+You can confirm it worked by sending a message like this:
+`@conduit:your.server.name: list_appservices`
+
+The @conduit bot should answer with `Appservices (1): your-bridge`
+
+Then you are done. Conduit will send messages to the appservices and the
+appservice can send requests to the homeserver. You don't need to restart
+Conduit, but if it doesn't work, restarting while the appservice is running
+could help.
diff --git a/DEPLOY.md b/DEPLOY.md
index 8dedad2d..02073ff6 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -209,3 +209,5 @@ Set it to start automatically when your system boots with:
 ```bash
 $ sudo systemctl enable conduit
 ```
+
+If you want to set up an appservice, take a look at the [Appservice Guide](APPSERVICES.md).
diff --git a/README.md b/README.md
index ace30eb4..591313f2 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,10 @@ Check out the [Conduit 1.0 Release Milestone](https://gitlab.com/famedly/conduit
 Download or compile a Conduit binary, set up the config and call it from somewhere like a systemd script. [Read
 more](DEPLOY.md)
 
+If you want to connect an Appservice to Conduit, take a look at the [Appservice Guide](APPSERVICES.md).
+
+If you want to cross compile Conduit to another architecture, read the [Cross-Compile Guide](CROSS_COMPILE.md).
+
 ##### Deloy using a Debian package
 
 You need to have the `deb` helper command installed that creates Debian packages from Cargo projects (see [cargo-deb](https://github.com/mmstick/cargo-deb/) for more info):