From 315255b6b58ff1df7f69bd5ff3eabb223dd8c237 Mon Sep 17 00:00:00 2001 From: Emanuele Aliberti Date: Mon, 9 May 2022 09:06:11 +0200 Subject: [PATCH] Split INSTALL.md (WIP) --- docs/BUILD.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/INSTALL.md | 68 ++++++++++++++++++++----------------------------- 2 files changed, 94 insertions(+), 41 deletions(-) create mode 100644 docs/BUILD.md diff --git a/docs/BUILD.md b/docs/BUILD.md new file mode 100644 index 000000000..e19a8f514 --- /dev/null +++ b/docs/BUILD.md @@ -0,0 +1,67 @@ +# Building Dendrite + +## Prerequisites + +The following tools make up the minimum toolchain for building the +Dendrite binaries: + +* Go 1.16 or higher +* Gcc + +### Windows fast path + +If you want to build Dendrite on Windows: + +* `go` can be downloaded from [Go Downloads](https://go.dev/dl/); +* `gcc` can be downloaded from [MinGW-w64](https://www.mingw-w64.org/); + +Alternatively, if you use [Chocolatey](https://chocolatey.org/), +you can install *Go* and *Gcc* with the following command: + + choco install golang mingw -y + +## How to obtain the source code + +There are basically two ways of obtaining the Dendrite source code: + +* **clone** the [official Dendrite Git repository on GitHub](https://github.com/matrix-org/dendrite) + ```bash + git clone https://github.com/matrix-org/dendrite.git + cd dendrite + ``` +* **download** the archived source code of a specific release from the + official [release page](https://github.com/matrix-org/dendrite/releases); + the source code is provided in two different archives named - for + example, for version 0.8.2 - respectively `v0.8.2.zip` (Windows) and + `v0.8.2.tar.gz` (Linux and UNIX-like systems): just download the one + suitable for your development platform; + +Cloning the repository is of course suggested, if you intend to make +local changes to the code, or if you simply intend to follow the +evolution of Dendrite and test the changes before a new official version +is released. + +## How to build Dendrite + +However you got the Dendrite sources, to build the binaries, you have to +enter the `dendrite` directory before starting. + +### On Linux, or UNIX-like systems + +```bash +cd dendrite +./build.sh +``` + +### On Windows + +```dos +cd dendrite +build.cmd +``` + +If the build process ends successfully, the binary files can be found in +the `bin` directory inside the starting `dendrite` directory. + +From now on, you can start [installing or updating Dendrite](INSTALL.md) +on the server of your choice. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index ca1316aca..39ddf4e60 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,6 +1,11 @@ # Installing Dendrite -Dendrite can be run in one of two configurations: +> Be advised that Dendrite is still in development and it's not recommended for +> use in production environments just yet! + +## Dendrite Running Mode + +Dendrite can be run in one of two configurations ("*mode*"): * **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) @@ -14,56 +19,37 @@ Dendrite can be run in one of two configurations: 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**. +> In almost all cases, it is **recommended to run in monolith mode with PostgreSQL databases**. -Regardless of whether you are running in polylith or monolith mode, each Dendrite component that +Regardless of whether you are running in *polylith* or *monolith* mode, each Dendrite component that requires storage has its own database connections. Both Postgres and SQLite are supported and can be mixed-and-matched across components as needed in the configuration file. -Be advised that Dendrite is still in development and it's not recommended for -use in production environments just yet! - ## 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 - ``` +* Monolith Dendrite requires: + * if using PostgreSQL database(s) + * PostgreSQL 12 or higher + * if using SQLite databases + * ... +* Polylith Dendrite requires: + * if using PostgreSQL database(s) + * PostgreSQL 12 or higher + * A standalone [NATS Server](https://github.com/nats-io/nats-server) deployment with JetStream enabled + * if using SQLite databases + * A standalone [NATS Server](https://github.com/nats-io/nats-server) deployment with JetStream enabled ## Install NATS Server +> An independent NATS server is *only **required** for installation of +> Dentrite in polylith mode*. Dendrite in monolith mode uses, by +> default, an in-process NATS server, but there is no reason +> why an external one should not be used, if for example it is already +> available on the machine where Dendrite will be installed. + 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`, +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 @@ -106,7 +92,7 @@ On macOS, omit `sudo -u postgres` from the below commands. ### 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! +> **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