More updates

docs/CONTRIBUTING.md

@@ -40,8 +40,8 @@ does. If there are statements that are not obvious, please comment what they do.
 
 We also have some special tags which we use for searchability. These are:
 
-* `// TODO:` for places where a future review, rewrite or refactor is likely required
-* `// FIXME:` for places where we know there is an outstanding bug that needs a fix
+* `// TODO:` for places where a future review, rewrite or refactor is likely required;
+* `// FIXME:` for places where we know there is an outstanding bug that needs a fix;
 * `// NOTSPEC:` for places where the behaviour specifically does not match what the
   [Matrix Specification](https://spec.matrix.org/) prescribes, along with a description
   of *why* that is the case.

docs/_config.yml

@@ -8,3 +8,7 @@ github_username: matrix-org
 remote_theme: just-the-docs/just-the-docs
 plugins:
   - jekyll-feed
+aux_links:
+  "GitHub":
+    - "//github.com/matrix-org/dendrite"
+aux_links_new_tab: true

docs/administration/1_createusers.md

@@ -0,0 +1,53 @@
+---
+title: Creating user accounts
+parent: Administration
+permalink: /administration/createusers
+nav_order: 1
+---
+
+# Creating user accounts
+
+User accounts can be created on a Dendrite instance in a number of ways.
+
+## From the command line
+
+The `create-account` tool is built in the `bin` folder when building Dendrite with
+the `build.sh` script.
+
+It uses the `dendrite.yaml` configuration file to connect to the Dendrite user database
+and create the account entries directly. It can therefore be used even if Dendrite is not
+running yet, as long as the database is up.
+
+An example of using `create-account` to create a **normal account**:
+
+```bash
+./bin/create-account -config /path/to/dendrite.yaml -username USERNAME
+```
+
+You will be prompted to enter a new password for the new account.
+
+To create a new **admin account**, add the `-admin` flag:
+
+```bash
+./bin/create-account -config /path/to/dendrite.yaml -username USERNAME -admin
+```
+
+## Using shared secret registration
+
+Dendrite supports the Synapse-compatible shared secret registration endpoint.
+
+To enable shared secret registration, you must first enable it in the `dendrite.yaml`
+configuration file by specifying a shared secret. In the `client_api` section of the config,
+enter a new secret into the `registration_shared_secret` field:
+
+```yaml
+client_api:
+  # ...
+  registration_shared_secret: ""
+```
+
+You can then use the `/_synapse/admin/v1/register` endpoint as per the
+[Synapse documentation](https://matrix-org.github.io/synapse/latest/admin_api/register_api.html).
+
+Shared secret registration is only enabled once a secret is configured. To disable shared
+secret registration again, remove the secret from the configuration file.

docs/administration/2_registration.md

@@ -0,0 +1,53 @@
+---
+title: Enabling registration
+parent: Administration
+permalink: /administration/registration
+nav_order: 2
+---
+
+# Enabling registration
+
+Enabling registration allows users to register their own user accounts on your
+Dendrite server using their Matrix client. They will be able to choose their own
+username and password and log in.
+
+Registration is controlled by the `registration_disabled` field in the `client_api`
+section of the configuration. By default, `registration_disabled` is set to `true`,
+disabling registration. If you want to enable registration, you should change this
+setting to `false`.
+
+Currently Dendrite supports secondary verification using [reCAPTCHA](https://www.google.com/recaptcha/about/).
+Other methods will be supported in the future.
+
+## reCAPTCHA verification
+
+Dendrite supports reCAPTCHA as a secondary verification method. If you want to enable
+registration, it is **highly recommended** to configure reCAPTCHA. This will make it
+much more difficult for automated spam systems from registering accounts on your
+homeserver automatically.
+
+You will need an API key from the [reCAPTCHA Admin Panel](https://www.google.com/recaptcha/admin).
+Then configure the relevant details in the `client_api` section of the configuration:
+
+```yaml
+client_api:
+  # ...
+  registration_disabled: false
+  recaptcha_public_key: "PUBLIC_KEY_HERE"
+  recaptcha_private_key: "PRIVATE_KEY_HERE"
+  enable_registration_captcha: true
+  captcha_bypass_secret: ""
+  recaptcha_siteverify_api: "https://www.google.com/recaptcha/api/siteverify"
+```
+
+## Open registration
+
+Dendrite does support open registration — that is, allowing users to create their own
+user accounts without any verification or secondary authentication. However, it
+is **not recommended** to enable open registration, as this leaves your homeserver
+vulnerable to abuse by spammers or attackers, who create large numbers of user
+accounts on Matrix homeservers in order to send spam or abuse into the network.
+
+It isn't possible to enable open registration in Dendrite in a single step. If you
+try to disable the `registration_disabled` option without any secondary verification
+methods enabled (such as reCAPTCHA), Dendrite will log an error and fail to start.

docs/administration/3_presence.md

@@ -0,0 +1,39 @@
+---
+title: Enabling presence
+parent: Administration
+permalink: /administration/presence
+nav_order: 3
+---
+
+# Enabling presence
+
+Dendrite supports presence, which allows you to send your online/offline status
+to other users, and to receive their statuses automatically. They will be displayed
+by supported clients.
+
+Note that enabling presence **can negatively impact** the performance of your Dendrite
+server — it will require more CPU time and will increase the "chattiness" of your server
+over federation. It is disabled by default for this reason.
+
+Dendrite has two options for controlling presence:
+
+* **Enable inbound presence**: Dendrite will handle presence updates for remote users
+  and distribute them to local users on your homeserver;
+* **Enable outbound presence**: Dendrite will generate presence notifications for your
+  local users and distribute them to remote users over the federation.
+
+This means that you can configure only one or other direction if you prefer, i.e. to
+receive presence from other servers without revealing the presence of your own users.
+
+## Configuring presence
+
+Presence is controlled by the `presence` block in the `global` section of the
+configuration file:
+
+```yaml
+global:
+  # ...
+  presence:
+    enable_inbound: false
+    enable_outbound: false
+```

docs/administration/4_adminapi.md

@@ -0,0 +1,25 @@
+---
+title: Supported admin APIs
+parent: Administration
+permalink: /administration/adminapi
+---
+
+# Supported admin APIs
+
+Dendrite supports, at present, a very small number of endpoints that allow
+admin users to perform administrative functions. Please note that there is no
+API stability guarantee on these endpoints at present — they may change shape
+without warning.
+
+More endpoints will be added in the future.
+
+## `/_dendrite/admin/evacuateRoom/{roomID}`
+
+This endpoint will instruct Dendrite to part all local users from the given `roomID`
+in the URL. It may take some time to complete. A JSON body will be returned containing
+the user IDs of all affected users.
+
+## `/_synapse/admin/v1/register`
+
+Shared secret registration — please see the [user creation page](createusers) for
+guidance on configuring and using this endpoint.

docs/administration/adminapi.md

@@ -1,6 +0,0 @@
----
-title: Admin APIs
-parent: Administration
----
-
-# Admin APIs

docs/index.md

@@ -5,7 +5,19 @@ nav_exclude: true
 
 # Dendrite
 
-Dendrite is a second-generation Matrix homeserver written in Go!
+Dendrite is a second-generation Matrix homeserver written in Go! Following the microservice
+architecture model, Dendrite is designed to be efficient, reliable and scalable. Despite being beta,
+many Matrix features are already supported.
 
-Following the microservice architecture model, Dendrite is designed to be efficient,
-reliable and scalable. Despite being beta, many Matrix features are already supported.
+This site aims to include relevant documentation to help you to get started with and
+run Dendrite. Check out the following sections:
+
+* **[Installation](INSTALL.md)** for building and deploying your own Dendrite homeserver
+* **[Administration](administration.md)** for managing an existing Dendrite deployment
+* **[Development](development.md)** for developing against Dendrite
+
+You can also join us in our Matrix rooms dedicated to Dendrite:
+
+* **[#dendrite:matrix.org](https://matrix.to/#/#dendrite:matrix.org)** for general project discussion and support
+* **[#dendrite-dev:matrix.org](https://matrix.to/#/#dendrite-dev:matrix.org)** for chat on Dendrite development specifically
+* **[#dendrite-alerts:matrix.org](https://matrix.to/#/#dendrite-alerts:matrix.org)** for release notifications and other important announcements

docs/installation/6_install_polylith.md

@@ -17,7 +17,7 @@ go install ./cmd/dendrite-polylith-multi
 Alternatively, you can specify a custom path for the binary to be written to using `go build`:
 
 ```sh
-go install -o /usr/local/bin/ ./cmd/dendrite-polylith-multi
+go build -o /usr/local/bin/ ./cmd/dendrite-polylith-multi
 ```
 
 The `dendrite-polylith-multi` binary is a "multi-personality" binary which can run as