From d7824ed5b1b677ad5ea5fe84d1131a5d386b0c7e Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Mon, 14 Dec 2020 09:42:27 +0000 Subject: [PATCH] Update INSTALL.md (#1637) --- docs/INSTALL.md | 49 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index d881e73f..f51660e4 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -80,12 +80,6 @@ brew services start kafka ## Configuration -### SQLite database setup - -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. - ### PostgreSQL database setup Assuming that PostgreSQL 9.6 (or later) is installed: @@ -96,7 +90,23 @@ Assuming that PostgreSQL 9.6 (or later) is installed: sudo -u postgres createuser -P dendrite ``` -* Create the component databases: +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 signingkeyserver federationsender appservice keyserver userapi_account userapi_device naffka; do @@ -104,14 +114,22 @@ Assuming that PostgreSQL 9.6 (or later) is installed: done ``` -(On macOS, omit `sudo -u postgres` from the above commands.) + ... 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 +* A unique Matrix signing private key +* A valid and trusted TLS certificate and private key To generate a Matrix signing private key: @@ -119,7 +137,7 @@ To generate a Matrix signing private key: ./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 +**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. @@ -129,8 +147,8 @@ For testing, you can generate a self-signed certificate and key, although this w ./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 +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 @@ -140,7 +158,9 @@ Create config file, based on `dendrite-config.yaml`. Call it `dendrite.yaml`. Th * 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` + * 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. * The `use_naffka` option if using Naffka in a monolith deployment @@ -295,4 +315,3 @@ amongst other things. ```bash ./bin/dendrite-polylith-multi --config=dendrite.yaml userapi ``` -