9.8 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
- Go 1.8+
- Postgres 9.5+
- For Kafka (optional if using the monolith server):
- Unix-based system (https://kafka.apache.org/documentation/#os)
- JDK 1.8+ / OpenJDK 1.8+
- Apache Kafka 0.10.2+ (see scripts/install-local-kafka.sh for up-to-date version numbers)
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
On MacOS, you can use homebrew for easier setup of kafka
brew install kafka
brew services start zookeeper
brew services start kafka
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
(On macOS, omit sudo -u postgres from the above commands.)
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_namedatabase/*
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