dendrite/INSTALL.md
Erik Johnston 9476a266bd
Add database.naffka to example config (#350)
* Add database.naffka to example config

* Update dendrite-config.yaml

* Add naffka creation to INSTALL
2017-11-22 15:46:49 +00:00

9.6 KiB

Installing Dendrite

Dendrite can be run in one of two configurations:

  • A cluster of individual components, dealing with different aspects of the Matrix protocol (see WIRING.md). Components communicate with one another via Apache Kafka.

  • A monolith server, in which all components run in the same process. In this configuration, Kafka can be replaced with an in-process implementation called naffka.

Requirements

Setting up a development environment

Assumes Go 1.8 and JDK 1.8 are already installed and are on PATH.

# Get the code
git clone https://github.com/matrix-org/dendrite
cd dendrite

# Build it
go get github.com/constabulary/gb/...
gb build

If using Kafka, install and start it (c.f. scripts/install-local-kafka.sh):

MIRROR=http://apache.mirror.anlx.net/kafka/0.10.2.0/kafka_2.11-0.10.2.0.tgz

# Only download the kafka if it isn't already downloaded.
test -f kafka.tgz || wget $MIRROR -O kafka.tgz
# Unpack the kafka over the top of any existing installation
mkdir -p kafka && tar xzf kafka.tgz -C kafka --strip-components 1

# Start the zookeeper running in the background.
# By default the zookeeper listens on localhost:2181
kafka/bin/zookeeper-server-start.sh -daemon kafka/config/zookeeper.properties

# Start the kafka server running in the background.
# By default the kafka listens on localhost:9092
kafka/bin/kafka-server-start.sh -daemon kafka/config/server.properties

Configuration

Postgres database setup

Dendrite requires a postgres database engine, version 9.5 or later.

  • Create role:
    sudo -u postgres createuser -P dendrite     # prompts for password
    
  • Create databases:
    for i in account device mediaapi syncapi roomserver serverkey federationsender publicroomsapi naffka; do
        sudo -u postgres createdb -O dendrite dendrite_$i
    done
    

Crypto key generation

Generate the keys:

# Generate a self-signed SSL cert for federation:
test -f server.key || openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 3650 -nodes -subj /CN=localhost

# generate ed25519 signing key
test -f matrix_key.pem || ./bin/generate-keys -private-key matrix_key.pem

Configuration

Create config file, based on dendrite-config.yaml. Call it dendrite.yaml. Things that will need editing include at least:

  • server_name
  • database/*

Starting a monolith server

It is possible to use 'naffka' as an in-process replacement to Kafka when using the monolith server. To do this, set use_naffka: true in dendrite.yaml.

The monolith server can be started as shown below. By default it listens for HTTP connections on port 8008, so point your client at http://localhost:8008. If you set --tls-cert and --tls-key as shown below, it will also listen for HTTPS connections on port 8448.

./bin/dendrite-monolith-server --tls-cert=server.crt --tls-key=server.key

Starting a multiprocess server

The following contains scripts which will run all the required processes in order to point a Matrix client at Dendrite. Conceptually, you are wiring together to form the following diagram:


                                         /media   +---------------------------+
                      +----------->+------------->| dendrite-media-api-server |
                      ^            ^              +---------------------------+
                      |            |            :7774
                      |            |
                      |            |
                      |            |   /directory +----------------------------------+
                      |            |   +--------->| dendrite-public-rooms-api-server |<========++
                      |            |   |          +----------------------------------+         ||
                      |            |   |        :7775    |                                     ||
                      |            |   |    +<-----------+                                     ||
                      |            |   |    |                                                  ||
                      |            |   | /sync    +--------------------------+                 ||
                      |            |   +--------->| dendrite-sync-api-server |<================++
                      |            |   |    |     +--------------------------+                 ||
                      |            |   |    |   :7773    |         ^^                          ||
Matrix      +------------------+   |   |    |            |         ||    client_data           ||
Clients --->| client-api-proxy |-------+    +<-----------+         ++=============++           ||
            +------------------+   |   |    |                                     ||           ||
          :8008                    |   | CS API   +----------------------------+  ||           ||
                                   |   +--------->| dendrite-client-api-server |==++           ||
                                   |        |     +----------------------------+               ||
                                   |        |   :7771    |                                     ||
                                   |        |            |                                     ||
                                   |        +<-----------+                                     ||
                                   |        |                                                  ||
                                   |        |                                                  ||
                                   |        |           +----------------------+    room_event ||
                                   |        +---------->| dendrite-room-server |===============++
                                   |        |           +----------------------+               ||
                                   |        |         :7770                                    ||
                                   |        |                      ++==========================++
                                   |        +<------------+        ||
                                   |        |             |        VV
                                   |        |     +-----------------------------------+              Matrix
                                   |        |     | dendrite-federation-sender-server |------------> Servers
                                   |        |     +-----------------------------------+
                                   |        |   :7776
                                   |        |
                       +---------->+        +<-----------+
                       |                                 |
Matrix      +----------------------+  SS API  +--------------------------------+
Servers --->| federation-api-proxy |--------->| dendrite-federation-api-server |
            +----------------------+          +--------------------------------+
          :8448                             :7772


   A --> B  = HTTP requests (A = client, B = server)
   A ==> B  = Kafka (A = producer, B = consumer)

Run a client api proxy

This is what Matrix clients will talk to. If you use the script below, point your client at http://localhost:8008.

./bin/client-api-proxy \
--bind-address ":8008" \
--client-api-server-url "http://localhost:7771" \
--sync-api-server-url "http://localhost:7773" \
--media-api-server-url "http://localhost:7774" \
--public-rooms-api-server-url "http://localhost:7775" \

Run a client api

This is what implements message sending. Clients talk to this via the proxy in order to send messages.

./bin/dendrite-client-api-server --config=dendrite.yaml

(If this fails with pq: syntax error at or near "ON", check you are using at least postgres 9.5.)

Run a room server

This is what implements the room DAG. Clients do not talk to this.

./bin/dendrite-room-server --config=dendrite.yaml

Run a sync server

This is what implements /sync requests. Clients talk to this via the proxy in order to receive messages.

./bin/dendrite-sync-api-server --config dendrite.yaml

Run a media server

This implements /media requests. Clients talk to this via the proxy in order to upload and retrieve media.

./bin/dendrite-media-api-server --config dendrite.yaml

Run public room server

This implements /directory requests. Clients talk to this via the proxy in order to retrieve room directory listings.

./bin/dendrite-public-rooms-api-server --config dendrite.yaml

Run a federation api proxy

This is what Matrix servers will talk to. This is only required if you want to support federation.

./bin/federation-api-proxy \
--bind-address ":8448" \
--federation-api-url "http://localhost:7772" \
--media-api-server-url "http://localhost:7774" \

Run a federation api server

This implements federation requests. Servers talk to this via the proxy in order to send transactions. This is only required if you want to support federation.

./bin/dendrite-federation-api-server --config dendrite.yaml

Run a federation sender server

This sends events from our users to other servers. This is only required if you want to support federation.

./bin/dendrite-federation-sender-server --config dendrite.yaml