Docs restructure (#2953)

Needs to be merged into `gh-pages` later on.

docs/administration/1_createusers.md

@@ -11,10 +11,9 @@ 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.
+The `create-account` tool is built in the `bin` folder when [building](../installation/build) Dendrite.
 
-It uses the `dendrite.yaml` configuration file to connect to a running Dendrite instance and requires
+It uses the `dendrite.yaml` configuration file to connect to a **running** Dendrite instance and requires
 shared secret registration to be enabled as explained below.
 
 An example of using `create-account` to create a **normal account**:

docs/administration/4_adminapi.md

@@ -1,6 +1,7 @@
 ---
 title: Supported admin APIs
 parent: Administration
+nav_order: 4
 permalink: /administration/adminapi
 ---
 
@@ -49,13 +50,17 @@ the room IDs of all affected rooms.
 
 ## POST `/_dendrite/admin/resetPassword/{userID}`
 
-Reset the password of a local user.
+Reset the password of a local user. 
+
+**If `logout_devices` is set to `true`, all `access_tokens` will be invalidated, resulting
+in the potential loss of encrypted messages**
 
 Request body format:
 
-```
+```json
 {
-    "password": "new_password_here"
+    "password": "new_password_here",
+    "logout_devices": false
 }
 ```
 
@@ -68,11 +73,14 @@ Indexing is done in the background, the server logs every 1000 events (or below)
 
 This endpoint instructs Dendrite to immediately query `/devices/{userID}` on a federated server. An empty JSON body will be returned on success, updating all locally stored user devices/keys. This can be used to possibly resolve E2EE issues, where the remote user can't decrypt messages.
 
+## POST `/_dendrite/admin/purgeRoom/{roomID}`
+
+This endpoint instructs Dendrite to remove the given room from its database. Before doing so, it will evacuate all local users from the room. It does **NOT** remove media files. Depending on the size of the room, this may take a while. Will return an empty JSON once other components were instructed to delete the room.
 
 ## POST `/_synapse/admin/v1/send_server_notice`
 
 Request body format:
-```
+```json
 {
     "user_id": "@target_user:server_name",
     "content": {
@@ -85,7 +93,7 @@ Request body format:
 Send a server notice to a specific user. See the [Matrix Spec](https://spec.matrix.org/v1.3/client-server-api/#server-notices) for additional details on server notice behaviour.
 If successfully sent, the API will return the following response:
 
-```
+```json
 {
      "event_id": "<event_id>"
 }

docs/administration/5_optimisation.md

@@ -0,0 +1,101 @@
+---
+title: Optimise your installation
+parent: Administration
+has_toc: true
+nav_order: 5
+permalink: /administration/optimisation
+---
+
+# Optimise your installation
+
+Now that you have Dendrite running, the following tweaks will improve the reliability
+and performance of your installation.
+
+## PostgreSQL connection limit
+
+A PostgreSQL database engine is configured to allow only a certain number of connections.
+This is typically controlled by the `max_connections` and `superuser_reserved_connections`
+configuration items in `postgresql.conf`. Once these limits are violated, **PostgreSQL will
+immediately stop accepting new connections** until some of the existing connections are closed.
+This is a common source of misconfiguration and requires particular care.
+
+If your PostgreSQL `max_connections` is set to `100` and `superuser_reserved_connections` is
+set to `3` then you have an effective connection limit of 97 database connections. It is
+therefore important to ensure that Dendrite doesn't violate that limit, otherwise database
+queries will unexpectedly fail and this will cause problems both within Dendrite and for users.
+
+If you are also running other software that uses the same PostgreSQL database engine, then you
+must also take into account that some connections will be already used by your other software
+and therefore will not be available to Dendrite. Check the configuration of any other software
+using the same database engine for their configured connection limits and adjust your calculations
+accordingly.
+
+Dendrite has a `max_open_conns` configuration item in each `database` block to control how many
+connections it will open to the database.
+
+**If you are using the `global` database pool** then you only need to configure the
+`max_open_conns` setting once in the `global` section.
+
+You may wish to raise the `max_connections` limit on your PostgreSQL server to accommodate
+additional connections, in which case you should also update the `max_open_conns` in your
+Dendrite configuration accordingly. However be aware that this is only advisable on particularly
+powerful servers that can handle the concurrent load of additional queries running at one time.
+
+## File descriptor limit
+
+Most platforms have a limit on how many file descriptors a single process can open. All
+connections made by Dendrite consume file descriptors — this includes database connections
+and network requests to remote homeservers. When participating in large federated rooms
+where Dendrite must talk to many remote servers, it is often very easy to exhaust default
+limits which are quite low.
+
+We currently recommend setting the file descriptor limit to 65535 to avoid such
+issues. Dendrite will log immediately after startup if the file descriptor limit is too low:
+
+```
+level=warning msg="IMPORTANT: Process file descriptor limit is currently 1024, it is recommended to raise the limit for Dendrite to at least 65535 to avoid issues"
+```
+
+UNIX systems have two limits: a hard limit and a soft limit. You can view the soft limit
+by running `ulimit -Sn` and the hard limit with `ulimit -Hn`:
+
+```bash
+$ ulimit -Hn
+1048576
+
+$ ulimit -Sn
+1024
+```
+
+Increase the soft limit before starting Dendrite:
+
+```bash
+ulimit -Sn 65535
+```
+
+The log line at startup should no longer appear if the limit is sufficient.
+
+If you are running under a systemd service, you can instead add `LimitNOFILE=65535` option
+to the `[Service]` section of your service unit file.
+
+## DNS caching
+
+Dendrite has a built-in DNS cache which significantly reduces the load that Dendrite will
+place on your DNS resolver. This may also speed up outbound federation.
+
+Consider enabling the DNS cache by modifying the `global` section of your configuration file:
+
+```yaml
+  dns_cache:
+    enabled: true
+    cache_size: 4096
+    cache_lifetime: 600s
+```
+
+## Time synchronisation
+
+Matrix relies heavily on TLS which requires the system time to be correct. If the clock
+drifts then you may find that federation no works reliably (or at all) and clients may
+struggle to connect to your Dendrite server.
+
+Ensure that the time is synchronised on your system by enabling NTP sync.

docs/administration/6_troubleshooting.md

@@ -1,6 +1,7 @@
 ---
 title: Troubleshooting
 parent: Administration
+nav_order: 6
 permalink: /administration/troubleshooting
 ---
 
@@ -18,7 +19,7 @@ be clues in the logs.
 You can increase this log level to the more verbose `debug` level if necessary by adding
 this to the config and restarting Dendrite:
 
-```
+```yaml
 logging:
 - type: std
   level: debug
@@ -56,12 +57,7 @@ number of database connections does not exceed the maximum allowed by PostgreSQL
 
 Open your `postgresql.conf` configuration file and check the value of `max_connections`
 (which is typically `100` by default). Then open your `dendrite.yaml` configuration file
-and ensure that:
-
-1. If you are using the `global.database` section, that `max_open_conns` does not exceed
-   that number;
-2. If you are **not** using the `global.database` section, that the sum total of all
-   `max_open_conns` across all `database` blocks does not exceed that number.
+and ensure that in the `global.database` section, `max_open_conns` does not exceed that number.
 
 ## 5. File descriptors
 
@@ -77,7 +73,7 @@ If there aren't, you will see a log lines like this:
 level=warning msg="IMPORTANT: Process file descriptor limit is currently 65535, it is recommended to raise the limit for Dendrite to at least 65535 to avoid issues"
 ```
 
-Follow the [Optimisation](../installation/11_optimisation.md) instructions to correct the
+Follow the [Optimisation](5_optimisation.md) instructions to correct the
 available number of file descriptors.
 
 ## 6. STUN/TURN Server tester