Docs restructure (#2953)

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

docs/installation/manual/1_build.md

@@ -0,0 +1,33 @@
+---
+title: Building/Installing Dendrite
+parent: Manual
+grand_parent: Installation
+has_toc: true
+nav_order: 1
+permalink: /installation/manual/build
+---
+
+# Build all Dendrite commands
+
+Dendrite has numerous utility commands in addition to the actual server binaries.
+Build them all from the root of the source repo with:
+
+```sh
+go build -o bin/ ./cmd/...
+```
+
+The resulting binaries will be placed in the `bin` subfolder.
+
+# Installing Dendrite
+
+You can install the Dendrite binary into `$GOPATH/bin` by using `go install`:
+
+```sh
+go install ./cmd/dendrite
+```
+
+Alternatively, you can specify a custom path for the binary to be written to using `go build`:
+
+```sh
+go build -o /usr/local/bin/ ./cmd/dendrite
+```

docs/installation/manual/2_database.md

@@ -0,0 +1,87 @@
+---
+title: Preparing database storage
+parent: Installation
+nav_order: 2
+parent: Manual
+grand_parent: Installation
+permalink: /installation/manual/database
+---
+
+# Preparing database storage
+
+Dendrite uses SQL databases to store data. Depending on the database engine being used, you
+may need to perform some manual steps outlined below.
+
+## PostgreSQL
+
+Dendrite can automatically populate the database with the relevant tables and indexes, but
+it is not capable of creating the database itself. You will need to create the database
+manually.
+
+The database **must** be created with UTF-8 encoding configured, or you will likely run into problems
+with your Dendrite deployment.
+
+You will need to create a single PostgreSQL database. Deployments
+can use a single global connection pool, which makes updating the configuration file much easier.
+Only one database connection string to manage and likely simpler to back up the database. All
+components will be sharing the same database resources (CPU, RAM, storage).
+
+You will most likely want to:
+
+1. Configure a role (with a username and password) which Dendrite can use to connect to the
+   database;
+2. Create the database itself, ensuring that the Dendrite role has privileges over them.
+   As Dendrite will create and manage the database tables, indexes and sequences by itself, the
+   Dendrite role must have suitable privileges over the database.
+
+### Connection strings
+
+The format of connection strings for PostgreSQL databases is described in the [PostgreSQL libpq manual](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). Note that Dendrite only
+supports the "Connection URIs" format and **will not** work with the "Keyword/Value Connection
+string" format.
+
+Example supported connection strings take the format:
+
+* `postgresql://user:pass@hostname/database?options=...`
+* `postgres://user:pass@hostname/database?options=...`
+
+If you need to disable SSL/TLS on the database connection, you may need to append `?sslmode=disable` to the end of the connection string.
+
+### Role creation
+
+Create a role which Dendrite can use to connect to the database, choosing a new password when
+prompted. On macOS, you may need to omit the `sudo -u postgres` from the below instructions.
+
+```bash
+sudo -u postgres createuser -P dendrite
+```
+
+### Single database creation
+
+Create the database itself, using the `dendrite` role from above:
+
+```bash
+sudo -u postgres createdb -O dendrite -E UTF-8 dendrite
+```
+
+## SQLite
+
+**WARNING:** The Dendrite SQLite backend is slower, less reliable and not recommended for
+production usage. You should use PostgreSQL instead. We may not be able to provide support if
+you run into issues with your deployment while using the SQLite backend.
+
+SQLite deployments do not require manual database creation. Simply configure the database
+filenames in the Dendrite configuration file and start Dendrite. The databases will be created
+and populated automatically.
+
+Note that Dendrite **cannot share a single SQLite database across multiple components**. Each
+component must be configured with its own SQLite database filename. You will have to remove
+the `global.database` section from your Dendrite config and add it to each individual section
+instead in order to use SQLite.
+
+### Connection strings
+
+Connection strings for SQLite databases take the following forms:
+
+* Current working directory path: `file:dendrite_component.db`
+* Full specified path: `file:///path/to/dendrite_component.db`

docs/installation/manual/3_configuration.md

@@ -0,0 +1,125 @@
+---
+title: Configuring Dendrite
+parent: Manual
+grand_parent: Installation
+nav_order: 3
+permalink: /installation/manual/configuration
+---
+
+# Configuring Dendrite
+
+A YAML configuration file is used to configure Dendrite. A sample configuration file is
+present in the top level of the Dendrite repository:
+
+* [`dendrite-sample.yaml`](https://github.com/matrix-org/dendrite/blob/main/dendrite-sample.yaml)
+
+You will need to duplicate the sample, calling it `dendrite.yaml` for example, and then
+tailor it to your installation. At a minimum, you will need to populate the following
+sections:
+
+## Server name
+
+First of all, you will need to configure the server name of your Matrix homeserver.
+This must match the domain name that you have selected whilst [configuring the domain
+name delegation](domainname#delegation).
+
+In the `global` section, set the `server_name` to your delegated domain name:
+
+```yaml
+global:
+  # ...
+  server_name: example.com
+```
+
+## Server signing keys
+
+Next, you should tell Dendrite where to find your [server signing keys](signingkeys).
+
+In the `global` section, set the `private_key` to the path to your server signing key:
+
+```yaml
+global:
+  # ...
+  private_key: /path/to/matrix_key.pem
+```
+
+## JetStream configuration
+
+Dendrite deployments can use the built-in NATS Server rather than running a standalone
+server. If you want to use a standalone NATS Server anyway, you can also configure that too.
+
+### Built-in NATS Server
+
+In the `global` section, under the `jetstream` key, ensure that no server addresses are
+configured and set a `storage_path` to a persistent folder on the filesystem:
+
+```yaml
+global:
+  # ...
+  jetstream:
+    storage_path: /path/to/storage/folder
+    topic_prefix: Dendrite
+```
+
+### Standalone NATS Server
+
+To use a standalone NATS Server instance, you will need to configure `addresses` field
+to point to the port that your NATS Server is listening on:
+
+```yaml
+global:
+  # ...
+  jetstream:
+    addresses:
+      - localhost:4222
+    topic_prefix: Dendrite
+```
+
+You do not need to configure the `storage_path` when using a standalone NATS Server instance.
+In the case that you are connecting to a multi-node NATS cluster, you can configure more than
+one address in the `addresses` field.
+
+## Database connection using a global connection pool
+
+If you want to use a single connection pool to a single PostgreSQL database, 
+then you must uncomment and configure the `database` section within the `global` section:
+
+```yaml
+global:
+  # ...
+  database:
+    connection_string: postgres://user:pass@hostname/database?sslmode=disable
+    max_open_conns: 90
+    max_idle_conns: 5
+    conn_max_lifetime: -1
+```
+
+**You must then remove or comment out** the `database` sections from other areas of the
+configuration file, e.g. under the `app_service_api`, `federation_api`, `key_server`,
+`media_api`, `mscs`, `relay_api`, `room_server`, `sync_api` and `user_api` blocks, otherwise
+these will override the `global` database configuration.
+
+## Full-text search
+
+Dendrite supports full-text indexing using [Bleve](https://github.com/blevesearch/bleve). It is configured in the `sync_api` section as follows.
+
+Depending on the language most likely to be used on the server, it might make sense to change the `language` used when indexing, 
+to ensure the returned results match the expectations. A full list of possible languages 
+can be found [here](https://github.com/matrix-org/dendrite/blob/5b73592f5a4dddf64184fcbe33f4c1835c656480/internal/fulltext/bleve.go#L25-L46).
+
+```yaml
+sync_api:
+  # ...
+  search:
+    enabled: false
+    index_path: "./searchindex"
+    language: "en"
+```
+
+## Other sections
+
+There are other options which may be useful so review them all. In particular, if you are
+trying to federate from your Dendrite instance into public rooms then configuring the
+`key_perspectives` (like `matrix.org` in the sample) can help to improve reliability
+considerably by allowing your homeserver to fetch public keys for dead homeservers from
+another living server.

docs/installation/manual/4_signingkey.md

@@ -0,0 +1,80 @@
+---
+title: Generating signing keys
+parent: Manual
+grand_parent: Installation
+nav_order: 4
+permalink: /installation/manual/signingkeys
+---
+
+# Generating signing keys
+
+All Matrix homeservers require a signing private key, which will be used to authenticate
+federation requests and events.
+
+The `generate-keys` utility can be used to generate a private key. Assuming that Dendrite was
+built using `go build -o bin/ ./cmd/...`, you should find the `generate-keys` utility in the `bin` folder.
+
+To generate a Matrix signing private key:
+
+```bash
+./bin/generate-keys --private-key matrix_key.pem
+```
+
+The generated `matrix_key.pem` file is your new signing key.
+
+## Important warning
+
+You must treat this key as if it is highly sensitive and private, so **never share it with
+anyone**. No one should ever ask you for this key for any reason, even to debug a problematic
+Dendrite server.
+
+Make sure take a safe backup of this key. You will likely need it if you want to reinstall
+Dendrite, or any other Matrix homeserver, on the same domain name in the future. If you lose
+this key, you may have trouble joining federated rooms.
+
+## Old signing keys
+
+If you already have old signing keys from a previous Matrix installation on the same domain
+name, you can reuse those instead, as long as they have not been previously marked as expired —
+a key that has been marked as expired in the past is unusable.
+
+Old keys from a previous Dendrite installation can be reused as-is without any further
+configuration required. Simply use that key file in the Dendrite configuration.
+
+If you have server keys from an older Synapse instance, you can convert them to Dendrite's PEM
+format and configure them as `old_private_keys` in your config.
+
+## Key format
+
+Dendrite stores the server signing key in the PEM format with the following structure.
+
+```
+-----BEGIN MATRIX PRIVATE KEY-----
+Key-ID: ed25519:<Key ID>
+
+<Base64 Encoded Key Data>
+-----END MATRIX PRIVATE KEY-----
+```
+
+## Converting Synapse keys
+
+If you have signing keys from a previous Synapse installation, you should ideally configure them
+as `old_private_keys` in your Dendrite config file. Synapse stores signing keys in the following
+format:
+
+```
+ed25519 <Key ID> <Base64 Encoded Key Data>
+```
+
+To convert this key to Dendrite's PEM format, use the following template. You must copy the Key ID
+exactly without modifying it. **It is important to include the trailing equals sign on the Base64
+Encoded Key Data** if it is not already present in the original key, as the key data needs to be
+padded to exactly 32 bytes:
+
+```
+-----BEGIN MATRIX PRIVATE KEY-----
+Key-ID: ed25519:<Key ID>
+
+<Base64 Encoded Key Data>=
+-----END MATRIX PRIVATE KEY-----
+```

docs/installation/manual/5_starting_dendrite.md

@@ -0,0 +1,26 @@
+---
+title: Starting Dendrite
+parent: Manual
+grand_parent: Installation
+nav_order: 5
+permalink: /installation/manual/start
+---
+
+# Starting Dendrite
+
+Once you have completed all preparation and installation steps,
+you can start your Dendrite deployment by executing the `dendrite` binary:
+
+```bash
+./dendrite -config /path/to/dendrite.yaml
+```
+
+By default, Dendrite will listen HTTP on port 8008. If you want to change the addresses
+or ports that Dendrite listens on, you can use the `-http-bind-address` and
+`-https-bind-address` command line arguments:
+
+```bash
+./dendrite -config /path/to/dendrite.yaml \
+    -http-bind-address 1.2.3.4:12345 \
+    -https-bind-address 1.2.3.4:54321
+```