From dd1b381789925c5e9cc1c3f5ac2acefc9d317f44 Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Wed, 11 May 2022 11:56:39 +0100 Subject: [PATCH] Updates --- docs/FAQ.md | 2 +- docs/INSTALL.md | 183 -------------------------- docs/index.md | 6 +- docs/installation/configuration.md | 144 ++++++++++++++++++++ docs/installation/database.md | 105 +++++++++++++++ docs/installation/domainname.md | 92 +++++++++++++ docs/installation/install_monolith.md | 25 ++++ docs/installation/install_polylith.md | 26 ++++ docs/installation/monolith.md | 61 --------- docs/installation/planning.md | 102 ++++++++++++++ docs/installation/polylith.md | 27 ---- docs/installation/signingkey.md | 78 +++++++++++ docs/serverkeyformat.md | 34 ----- 13 files changed, 578 insertions(+), 307 deletions(-) create mode 100644 docs/installation/configuration.md create mode 100644 docs/installation/database.md create mode 100644 docs/installation/domainname.md create mode 100644 docs/installation/install_monolith.md create mode 100644 docs/installation/install_polylith.md delete mode 100644 docs/installation/monolith.md create mode 100644 docs/installation/planning.md delete mode 100644 docs/installation/polylith.md create mode 100644 docs/installation/signingkey.md delete mode 100644 docs/serverkeyformat.md diff --git a/docs/FAQ.md b/docs/FAQ.md index ab9723e94..f3ac025b8 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -3,7 +3,7 @@ title: FAQ nav_order: 1 --- -# Frequently Asked Questions +# FAQ ## Is Dendrite stable? diff --git a/docs/INSTALL.md b/docs/INSTALL.md index ea68e86de..b5a265c6f 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -4,190 +4,7 @@ has_children: true nav_order: 2 --- -# Installing Dendrite -Dendrite can be run in one of two configurations: - -* **Monolith mode**: All components run in the same process. In this mode, - it is possible to run an in-process [NATS Server](https://github.com/nats-io/nats-server) - instead of running a standalone deployment. This will usually be the preferred model for - low-to-mid volume deployments, providing the best balance between performance and resource usage. - -* **Polylith mode**: A cluster of individual components running in their own processes, dealing - with different aspects of the Matrix protocol (see [WIRING.md](WIRING-Current.md)). Components - communicate with each other using internal HTTP APIs and [NATS Server](https://github.com/nats-io/nats-server). - This will almost certainly be the preferred model for very large deployments but scalability - comes with a cost. API calls are expensive and therefore a polylith deployment may end up using - disproportionately more resources for a smaller number of users compared to a monolith deployment. - -In almost all cases, it is **recommended to run in monolith mode with PostgreSQL databases**. - -## Requirements - -Dendrite requires: - -* Go 1.16 or higher -* PostgreSQL 12 or higher (if using PostgreSQL databases, not needed for SQLite) - -If you want to run a polylith deployment, you also need: - -* A standalone [NATS Server](https://github.com/nats-io/nats-server) deployment with JetStream enabled - -If you want to build it on Windows, you need `gcc` in the path: - -* [MinGW-w64](https://www.mingw-w64.org/) - -## Building Dendrite - -Start by cloning the code: - -```bash -git clone https://github.com/matrix-org/dendrite -cd dendrite -``` - -Then build it: - -* Linux or UNIX-like systems: - - ```bash - ./build.sh - ``` - -* Windows: - - ```dos - build.cmd - ``` - -## Install NATS Server - -Follow the [NATS Server installation instructions](https://docs.nats.io/running-a-nats-service/introduction/installation) and then [start your NATS deployment](https://docs.nats.io/running-a-nats-service/introduction/running). - -JetStream must be enabled, either by passing the `-js` flag to `nats-server`, -or by specifying the `store_dir` option in the the `jetstream` configuration. - -## Configuration - -### PostgreSQL database setup - -Assuming that PostgreSQL 12 (or later) is installed: - -* Create role, choosing a new password when prompted: - - ```bash - sudo -u postgres createuser -P dendrite - ``` - -At this point you have a choice on whether to run all of the Dendrite -components from a single database, or for each component to have its -own database. For most deployments, running from a single database will -be sufficient, although you may wish to separate them if you plan to -split out the databases across multiple machines in the future. - -On macOS, omit `sudo -u postgres` from the below commands. - -* If you want to run all Dendrite components from a single database: - - ```bash - sudo -u postgres createdb -O dendrite dendrite - ``` - - ... in which case your connection string will look like `postgres://user:pass@database/dendrite`. - -* If you want to run each Dendrite component with its own database: - - ```bash - for i in mediaapi syncapi roomserver federationapi appservice keyserver userapi_accounts; do - sudo -u postgres createdb -O dendrite dendrite_$i - done - ``` - - ... in which case your connection string will look like `postgres://user:pass@database/dendrite_componentname`. - -### SQLite database setup - -**WARNING:** SQLite is suitable for small experimental deployments only and should not be used in production - use PostgreSQL instead for any user-facing federating installation! - -Dendrite can use the built-in SQLite database engine for small setups. -The SQLite databases do not need to be pre-built - Dendrite will -create them automatically at startup. - -### Server key generation - -Each Dendrite installation requires: - -* A unique Matrix signing private key -* A valid and trusted TLS certificate and private key - -To generate a Matrix signing private key: - -```bash -./bin/generate-keys --private-key matrix_key.pem -``` - -**WARNING:** 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. - -For testing, you can generate a self-signed certificate and key, although this will not work for public federation: - -```bash -./bin/generate-keys --tls-cert server.crt --tls-key server.key -``` - -If you have server keys from an older Synapse instance, -[convert them](serverkeyformat.md#converting-synapse-keys) to Dendrite's PEM -format and configure them as `old_private_keys` in your config. - -### Configuration file - -Create config file, based on `dendrite-config.yaml`. Call it `dendrite.yaml`. Things that will need editing include *at least*: - -* The `server_name` entry to reflect the hostname of your Dendrite server -* The `database` lines with an updated connection string based on your - desired setup, e.g. replacing `database` with the name of the database: - * For Postgres: `postgres://dendrite:password@localhost/database`, e.g. - * `postgres://dendrite:password@localhost/dendrite_userapi_account` to connect to PostgreSQL with SSL/TLS - * `postgres://dendrite:password@localhost/dendrite_userapi_account?sslmode=disable` to connect to PostgreSQL without SSL/TLS - * For SQLite on disk: `file:component.db` or `file:///path/to/component.db`, e.g. `file:userapi_account.db` - * Postgres and SQLite can be mixed and matched on different components as desired. -* Either one of the following in the `jetstream` configuration section: - * The `addresses` option — a list of one or more addresses of an external standalone - NATS Server deployment - * The `storage_path` — where on the filesystem the built-in NATS server should - store durable queues, if using the built-in NATS server - -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 `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 somewhere else. - -**WARNING:** Dendrite supports running all components from the same database in -PostgreSQL mode, but this is **NOT** a supported configuration with SQLite. When -using SQLite, all components **MUST** use their own database file. - -## Starting a monolith server - -The monolith server can be started as shown below. By default it listens for -HTTP connections on port 8008, so you can configure your Matrix client to use -`http://servername:8008` as the server: - -```bash -./bin/dendrite-monolith-server -``` - -If you set `--tls-cert` and `--tls-key` as shown below, it will also listen -for HTTPS connections on port 8448: - -```bash -./bin/dendrite-monolith-server --tls-cert=server.crt --tls-key=server.key -``` - -If the `jetstream` section of the configuration contains no `addresses` but does -contain a `store_dir`, Dendrite will start up a built-in NATS JetStream node -automatically, eliminating the need to run a separate NATS server. ## Starting a polylith deployment diff --git a/docs/index.md b/docs/index.md index 81f28d1ea..77fa8662b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,11 @@ --- layout: home +nav_exclude: true --- +# Dendrite + Dendrite is a second-generation Matrix homeserver written in Go! -This documentation is a work in progress. +Following the microservice architecture model, Dendrite is designed to be efficient, +reliable and scalable. Despite being beta, many Matrix features are already supported. diff --git a/docs/installation/configuration.md b/docs/installation/configuration.md new file mode 100644 index 000000000..247fd809e --- /dev/null +++ b/docs/installation/configuration.md @@ -0,0 +1,144 @@ +--- +title: Populate the configuration +parent: Installation +nav_order: 7 +--- + +# Populate the configuration + +The configuration file is used to configure Dendrite. A sample configuration file, +called [`dendrite-config.yaml`](https://github.com/matrix-org/dendrite/blob/main/dendrite-config.yaml), +is present in the top level of the Dendrite repository. + +You will need to duplicate this file, 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.md). + +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](signingkey.md). + +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 + +Monolith deployments can use the built-in NATS Server rather than running a standalone +server. If you are building a polylith deployment, or you want to use a standalone NATS +Server anyway, you can also configure that too. + +### Built-in NATS Server (monolith only) + +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: + in_memory: false + storage_path: /path/to/storage/folder + topic_prefix: Dendrite +``` + +### Standalone NATS Server (monolith and polylith) + +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 connections + +Configuring database connections varies based on the [database configuration](database.md) +that you chose. + +### Global connection pool (monolith with a single PostgreSQL database only) + +If you are running a monolith deployment and 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: 100 + 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`, `room_server`, `sync_api` and `user_api` blocks, otherwise these will +override the `global` database configuration. + +### Per-component connections (all other configurations) + +If you are building a polylith deployment, are using SQLite databases or separate PostgreSQL +databases per component, then you must instead configure the `database` sections under each +of the component blocks ,e.g. under the `app_service_api`, `federation_api`, `key_server`, +`media_api`, `mscs`, `room_server`, `sync_api` and `user_api` blocks. + +For example, with PostgreSQL: + +```yaml +room_server: + # ... + database: + connection_string: postgres://user:pass@hostname/dendrite_component?sslmode=disable + max_open_conns: 10 + max_idle_conns: 2 + conn_max_lifetime: -1 +``` + +... or with SQLite: + +```yaml +room_server: + # ... + database: + connection_string: file:roomserver.db + max_open_conns: 10 + max_idle_conns: 2 + conn_max_lifetime: -1 +``` + +## 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. diff --git a/docs/installation/database.md b/docs/installation/database.md new file mode 100644 index 000000000..9458b5157 --- /dev/null +++ b/docs/installation/database.md @@ -0,0 +1,105 @@ +--- +title: Preparing database storage +parent: Installation +nav_order: 3 +--- + +# 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. + +## SQLite + +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. + +### 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` + +## PostgreSQL + +Dendrite can automatically populate the database with the relevant tables and indexes, but +it is not capable of creating the databases themselves. You will need to create the databases +manually. + +At this point, you can choose to either use a single database for all Dendrite components, +or you can run each component with its own separate database: + +* **Single database**: You will need to create a single PostgreSQL database. Monolith 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). + +* **Separate databases**: You will need to create a separate PostgreSQL database for each + component. You will need to configure each component that has storage in the Dendrite + configuration file with its own connection parameters. Allows running a different database engine + for each component on a different machine if needs be, each with their own CPU, RAM and storage — + almost certainly overkill unless you are running a very large Dendrite deployment. + +For either configuration, you will want to: + +1. Configure a role (with a username and password) which Dendrite can use to connect to the + database; +2. Create the database(s) themselves, 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 + +Connection strings for PostgreSQL databases take the following form: + +* `postgres://user:pass@hostname/database?options=...` + +For example, if you have a role called `dendrite` with the password `foobarbaz`, a database named +`dendrite` running on the same local machine, your connection string will be +`postgres://dendrite:foobarbaz@localhost/dendrite`. + +If you need to disable SSL/TLS on the database connection, you can 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 dendrite +``` + +### Multiple database creation + +The following eight components require a database. In this example they will be named: + +| Appservice API | `dendrite_appservice` | +| Federation API | `dendrite_federationapi` | +| Media API | `dendrite_mediaapi` | +| MSCs | `dendrite_mscs` | +| Roomserver | `dendrite_roomserver` | +| Sync API | `dendrite_syncapi` | +| Key server | `dendrite_keyserver` | +| User API | `dendrite_userapi` | + +... therefore you will need to create eight different databases: + +```bash +for i in appservice federationapi mediaapi mscs roomserver syncapi keyserver userapi; do + sudo -u postgres createdb -O dendrite dendrite_$i +done +``` diff --git a/docs/installation/domainname.md b/docs/installation/domainname.md new file mode 100644 index 000000000..cd0f1e84e --- /dev/null +++ b/docs/installation/domainname.md @@ -0,0 +1,92 @@ +--- +title: Setting up the domain +parent: Installation +nav_order: 2 +--- + +# Setting up the domain + +Every Matrix server deployment requires a server name which uniquely identifies it. For +example, if you are using the server name `example.com`, then your users will have usernames +that take the format `@user:example.com`. + +For federation to work, the server name must be resolvable by other homeservers on the internet +— that is, the domain must be registered and properly configured with the relevant DNS records. + +Matrix servers discover each other when federating using the following methods: + +1. If a well-known delegation exists on `example.com`, use the path server from the + well-known file to connect to the remote homeserver; +2. If a DNS SRV delegation exists on `example.com`, use the hostname and port from the DNS SRV + record to connect to the remote homeserver; +3. If neither well-known or DNS SRV delegation are configured, attempt to connect to the remote + homeserver by connecting to `example.com` port TCP/8448 using HTTPS. + +## TLS certificates + +Matrix federation requires that valid TLS certificates are present on the domain. You must +obtain certificates from a publicly accepted Certificate Authority (CA). [LetsEncrypt](https://letsencrypt.org) +is an example of such a CA that can be used. Self-signed certificates are not suitable for +federation and will typically not be accepted by other homeservers. + +A common practice to help ease the management of certificates is to install a reverse proxy in +front of Dendrite which manages the TLS certificates and HTTPS proxying itself. Software such as +[NGINX](https://www.nginx.com) and [HAProxy](http://www.haproxy.org) can be used for the task. +Although the finer details of configuring these are not described here, you must reverse proxy +all `/_matrix` paths to your Dendrite server. + +It is possible for the reverse proxy to listen on the standard HTTPS port TCP/443 so long as your +domain delegation is configured to point to port TCP/443. + +## Delegation + +Delegation allows you to specify the server name and port that your Dendrite installation is +reachable at, or to host the Dendrite server at a different server name to the domain that +is being delegated. + +For example, if your Dendrite installation is actually reachable at `matrix.example.com` port 8448, +you will be able to delegate from `example.com` to `matrix.example.com` so that your users will have +`@user:example.com` user names instead of `@user:matrix.example.com` usernames. + +Delegation can be performed in one of two ways: + +* **Well-known delegation**: A well-known text file is served over HTTPS on the domain name + that you want to use, pointing to your server on `matrix.example.com` port 8448; +* **DNS SRV delegation**: A DNS SRV record is created on the domain name that you want to + use, pointing to your server on `matrix.example.com` port TCP/8448. + +If you are using a reverse proxy to forward `/_matrix` to Dendrite, your well-known or DNS SRV +delegation must refer to the hostname and port that the reverse proxy is listening on instead. + +Well-known delegation is typically easier to set up and usually preferred. However, you can use +either or both methods to delegate. If you configure both methods of delegation, it is important +that they both agree and refer to the same hostname and port. + +## Well-known delegation + +Using well-known delegation requires that you are running a web server at `example.com` which +is listening on the standard HTTPS port TCP/443. + +Assuming that your Dendrite installation is listening for HTTPS connections at `matrix.example.com` +on port 8448, the delegation file must be served at `https://example.com/.well-known/matrix/server` +and contain the following JSON document: + +```json +{ + "m.server": "https://matrix.example.com:8448" +} +``` + +## DNS SRV delegation + +Using DNS SRV delegation requires creating DNS SRV records on the `example.com` zone which +refer to your Dendrite installation. + +Assuming that your Dendrite installation is listening for HTTPS connections at `matrix.example.com` +port 8448, the DNS SRV record must have the following fields: + +* Name: `@` (or whichever term your DNS provider uses to signal the root) +* Service: `_matrix` +* Protocol: `_tcp` +* Port: `8448` +* Target: `matrix.example.com` diff --git a/docs/installation/install_monolith.md b/docs/installation/install_monolith.md new file mode 100644 index 000000000..58750e045 --- /dev/null +++ b/docs/installation/install_monolith.md @@ -0,0 +1,25 @@ +--- +title: Installing as a monolith +parent: Installation +has_toc: true +nav_order: 5 +--- + +# Installing as a monolith + +On UNIX systems, the `build.sh` script will build all variants of Dendrite. + +```bash +./build.sh +``` + +The `bin` directory will contain the built binaries. + +For monolith deployments, the relevant binary is the `dendrite-monolith-server` +binary. + +Copy the `./bin/dendrite-monolith-server` into a relevant system path, for example: + +```bash +cp ./bin/dendrite-monolith-server /usr/local/bin/ +``` diff --git a/docs/installation/install_polylith.md b/docs/installation/install_polylith.md new file mode 100644 index 000000000..54ad8a293 --- /dev/null +++ b/docs/installation/install_polylith.md @@ -0,0 +1,26 @@ +--- +title: Installing as a polylith +parent: Installation +has_toc: true +nav_order: 6 +--- + +# Installing as a polylith + +On UNIX systems, the `build.sh` script will build all variants of Dendrite. + +```sh +./build.sh +``` + +The `bin` directory will contain the built binaries. + +For polylith deployments, the relevant binary is the `dendrite-polylith-multi` +binary, which is a "multi-personality" binary which can run as any of the components +depending on the supplied command line parameters. + +Copy the `./bin/dendrite-polylith-multi` into a relevant system path, for example: + +```bash +cp ./bin/dendrite-polylith-multi /usr/local/bin/ +``` diff --git a/docs/installation/monolith.md b/docs/installation/monolith.md deleted file mode 100644 index deee7f7f7..000000000 --- a/docs/installation/monolith.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Monolith -parent: Installation -has_toc: true ---- - -# Monolith Installation - -## Requirements - -In order to build a polylith deployment, you will need to install: - -* Go 1.16 or later -* PostgreSQL 12 or later - -## Build Dendrite - -On UNIX systems, the `build.sh` script will build all variants of Dendrite. - -```bash -./build.sh -``` - -The `bin` directory will contain the built binaries. - -## PostgreSQL setup - -First of all, you will need to create a PostgreSQL user that Dendrite can use -to connect to the database. - - ```bash - sudo -u postgres createuser -P dendrite - ``` - -At this point you have a choice on whether to run all of the Dendrite -components from a single database, or for each component to have its -own database. For most deployments, running from a single database will -be sufficient, although you may wish to separate them if you plan to -split out the databases across multiple machines in the future. - -On macOS, omit `sudo -u postgres` from the below commands. - -### Single database - -```bash -sudo -u postgres createdb -O dendrite dendrite -``` - -... in which case your connection string will look like `postgres://user:pass@database/dendrite`. - -### Separate databases - -```bash -for i in mediaapi syncapi roomserver federationapi appservice keyserver userapi_accounts; do - sudo -u postgres createdb -O dendrite dendrite_$i -done -``` - -... in which case your connection string will look like `postgres://user:pass@database/dendrite_componentname`. - -## Configuration file diff --git a/docs/installation/planning.md b/docs/installation/planning.md new file mode 100644 index 000000000..a102b9b77 --- /dev/null +++ b/docs/installation/planning.md @@ -0,0 +1,102 @@ +--- +title: Planning your installation +parent: Installation +nav_order: 1 +--- + +# Planning your installation + +## Modes + +Dendrite can be run in one of two configurations: + +* **Monolith mode**: All components run in the same process. In this mode, + it is possible to run an in-process NATS Server instead of running a standalone deployment. + This will usually be the preferred model for low-to-mid volume deployments, providing the best + balance between performance and resource usage. + +* **Polylith mode**: A cluster of individual components running in their own processes, dealing + with different aspects of the Matrix protocol. Components communicate with each other using + internal HTTP APIs and NATS Server. This will almost certainly be the preferred model for very + large deployments but scalability comes with a cost. API calls are expensive and therefore a + polylith deployment may end up using disproportionately more resources for a smaller number of + users compared to a monolith deployment. + +At present, we **recommend monolith mode deployments** in all cases. + +## Databases + +Dendrite can run with either a PostgreSQL or a SQLite backend. There are considerable tradeoffs +to consider: + +* **PostgreSQL**: Needs to run separately to Dendrite, needs to be installed and configured separately + and and will use more resources over all, but will be **considerably faster** than SQLite. PostgreSQL + has much better write concurrency which will allow Dendrite to process more tasks in parallel. This + will be necessary for federated deployments to perform adequately. + +* **SQLite**: Built into Dendrite, therefore no separate database engine is necessary and is quite + a bit easier to set up, but will be much slower than PostgreSQL in most cases. SQLite only allows a + single writer on a database at a given time, which will significantly restrict Dendrite's ability + to process multiple tasks in parallel. + +At this time, we **recommend the PostgreSQL database engine** for all production deployments. + +## Requirements + +Dendrite will run on Linux, macOS and Windows Server. It should also run fine on variants +of BSD such as FreeBSD and OpenBSD. We have not tested Dendrite on AIX, Solaris, Plan 9 or z/OS — +your mileage may vary with these platforms. + +It is difficult to state explicitly the amount of CPU, RAM or disk space that a Dendrite +installation will need, as this varies considerably based on a number of factors. In particular: + +* The number of users using the server; +* The number of rooms that the server is joined to — federated rooms in particular will typically + use more resources than rooms with only local users; +* The complexity of rooms that the server is joined to — rooms with more members coming and + going will typically be of a much higher complexity. + +Some tasks are more expensive than others, such as joining rooms over federation, running state +resolution or sending messages into very large federated rooms with lots of remote users. Therefore +you should plan accordingly and ensure that you have enough resources available to endure spikes +in CPU or RAM usage, as these may be considerably higher than the idle resource usage. + +At an absolute minimum, Dendrite will expect 1GB RAM. For a comfortable day-to-day deployment +which can participate in federated rooms for a number of local users, be prepared to assign 2-4 +CPU cores and 8GB RAM — more if your user count increases. + +If you are running PostgreSQL on the same machine, allow extra headroom for this too, as the +database engine will also have CPU and RAM requirements of its own. Running too many heavy +services on the same machine may result in resource starvation and processes may end up being +killed by the operating system if they try to use too much memory. + +## Dependencies + +In order to install Dendrite, you will need to satisfy the following dependencies. + +### Go + +At this time, Dendrite supports being built with Go 1.16 or later. We do not support building +Dendrite with older versions of Go than this. If you are installing Go using a package manager, +you should check (by running `go version`) that you are using a suitable version before you start. + +### PostgreSQL + +If using the PostgreSQL database engine, you should install PostgreSQL 12 or later. + +### NATS Server + +Monolith deployments come with a built-in [NATS Server](https://github.com/nats-io/nats-server) and +therefore do not need this to be manually installed. If you are planning a monolith installation, you +do not need to do anything. + +Polylith deployments, however, currently need a standalone NATS Server installation with JetStream +enabled. + +To do so, follow the [NATS Server installation instructions](https://docs.nats.io/running-a-nats-service/introduction/installation) and then [start your NATS deployment](https://docs.nats.io/running-a-nats-service/introduction/running). JetStream must be enabled, either by passing the `-js` flag to `nats-server`, +or by specifying the `store_dir` option in the the `jetstream` configuration. + +### Windows + +Finally, if you want to build Dendrite on Windows, you will need need `gcc` in the path. The best +way to achieve this is by installing and building Dendrite under [MinGW-w64](https://www.mingw-w64.org/). diff --git a/docs/installation/polylith.md b/docs/installation/polylith.md deleted file mode 100644 index b391a70a1..000000000 --- a/docs/installation/polylith.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Polylith -parent: Installation -has_toc: true ---- - -# Polylith Installation - -## Requirements - -In order to build a polylith deployment, you will need: - -* Go 1.16 or later -* PostgreSQL 12 or later -* NATS Server 2.8.0 or later - -## Build Dendrite - -On UNIX systems, the `build.sh` script will build all variants of Dendrite. - -```sh -./build.sh -``` - -## Database setup - -## Configuration file diff --git a/docs/installation/signingkey.md b/docs/installation/signingkey.md new file mode 100644 index 000000000..f3e4e36ee --- /dev/null +++ b/docs/installation/signingkey.md @@ -0,0 +1,78 @@ +--- +title: Generating signing keys +parent: Installation +nav_order: 4 +--- + +# 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 `build.sh`, 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: + + +-----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 +``` + +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: + += +-----END MATRIX PRIVATE KEY----- +``` diff --git a/docs/serverkeyformat.md b/docs/serverkeyformat.md deleted file mode 100644 index 3d1c9c117..000000000 --- a/docs/serverkeyformat.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Server Key Format -parent: Administration ---- - -# Server Key Format - -Dendrite stores the server signing key in the PEM format with the following structure. - -``` ------BEGIN MATRIX PRIVATE KEY----- -Key-ID: ed25519: - - ------END MATRIX PRIVATE KEY----- -``` - -## Converting Synapse Keys - -If you have signing keys from a previous synapse server, you should ideally configure them as `old_private_keys` in your Dendrite config file. Synapse stores signing keys in the following format. - -``` -ed25519 -``` - -To convert this key to Dendrite's PEM format, use the following template. **It is important to include the equals sign, as the key data needs to be padded to 32 bytes.** - -``` ------BEGIN MATRIX PRIVATE KEY----- -Key-ID: ed25519: - -= ------END MATRIX PRIVATE KEY----- -```