User:Maffblaster/Projects/Matrix

maff's landing page for setting up a Matrix server on Gentoo.

Todo

Finish writing ebuild for www-servers/synapse.
- Ebuild will need a user account.
- Research and add relevant USE flags.
- Tests? Should they be included? They don't seem necessary, but would conclude a 'perfect' ebuild.

Community resources

Nico's overlay contains a synapse build: https://gitlab.com/deepbluev7/neko
Gentoo project overlay for various matrix clients - https://gitweb.gentoo.org/repo/proj/matrix.git/

Done

Registered #gentoo-matrix (webchat) on Libera.Chat test bridging functionality.

Project links

https://github.com/matrix-org/synapse - The reference 'home server' (implemented in Python).
https://github.com/matrix-org/dendrite - 'Home server' implemented in go (future primary implementation).
https://github.com/matrix-org/gomatrix - A client (written in go).
https://github.com/matrix-org/matrix-doc - The docs (including the spec).
https://conduit.rs/ - Matrix server written in Rust.

Dendrite

Writing go ebuilds guide could be useful to help package this.

Prerequisites

dev-lang/go

Setup

Server

Instructions for getting a basic Dendrite test server quickly setup using an SQLite database:

user $

git clone https://github.com/matrix-org/dendrite

user $

cd dendrite

user $

git checkout v0.12.0 # Checkout the latest tagged release

user $

./build.sh

user $

./bin/generate-keys --private-key matrix_key.pem

user $

./bin/generate-keys --tls-cert server.crt --tls-key server.key

user $

cp dendrite-sample.yaml dendrite.yaml

Edit the dendrite.yaml configuration file to include the sqlite connection strings...

user $

mkdir sqlite

user $

touch sqlite/dendrite_{keyserver,roomserver,federation_api,media_api,relay_api,sync_api,user_api}.db

FILE dendrite.yamlModify the dendrite configuration file

# Global Matrix configuration. This configuration applies to all components.
global:
 # The domain name of this homeserver.
 server_name: localhost

#database:
    #connection_string: postgresql://username:password@hostname/dendrite?sslmode=disable
    #connection_string: ""
    #max_open_conns: 90
    #max_idle_conns: 5
    #conn_max_lifetime: -1

# Configuration for the Appservice API.
app_service_api:
  database:
    connection_string: file:sqlite/app_service_api.db
    max_open_conns: 10
    max_idle_conns: 2
    conn_max_lifetime: -1

# Configuration for the Federation API.
federation_api:
  database:
    connection_string: file:sqlite/federation_api.db
    max_open_conns: 10
    max_idle_conns: 2
    conn_max_lifetime: -1

key_server:
  database:
    connection_string: file:sqlite/dendrite_keyserver.db
    max_open_conns: 0
    max_idle_conns: 0
    conn_max_lifetime: 0

relay_api:
  database:
    connection_string: file:sqlite/dendrite_relay_api.db
    max_open_conns: 0
    max_idle_conns: 0
    conn_max_lifetime: 0

# Configuration for the Media API.
media_api:
  database:
    connection_string: file:sqlite/media_api.db
    max_open_conns: 10
    max_idle_conns: 2
    conn_max_lifetime: -1

# Configuration for enabling experimental MSCs on this homeserver.
mscs:
  database:
    connection_string: file:sqlite/mscs.db
    max_open_conns: 10
    max_idle_conns: 2
    conn_max_lifetime: -1

# Configuration for the Sync API.
sync_api:
  database:
    connection_string: file:sqlite/sync_api.db
    max_open_conns: 10
    max_idle_conns: 2
    conn_max_lifetime: -1

room_server:
  database:
    connection_string: file:sqlite/dendrite_roomserver.db
    max_open_conns: 0
    max_idle_conns: 0
    conn_max_lifetime: 0

# Configuration for the User API.
user_api:
  account_database:
    connection_string: file:sqlite/user_api.db
    max_open_conns: 0
    max_idle_conns: 0
    conn_max_lifetime: 0

The rest of the defaults in the file should work for this setup. Save and exit the file, then start the server:

user $

./bin/dendrite --tls-cert server.crt --tls-key server.key --config dendrite.yaml -http-bind-address 1.2.3.4:12345 -https-bind-address 1.2.3.4:5432

Insecure and secure connections for the server should run respectively on port 8008 (HTTP) and 8448 (HTTPS) by default.

Now with the server running, open a new terminal console to the current working directory and create some test users:

user $

 ./bin/create-account --config dendrite.yaml --username <YourUsername1> --password <SecretPassword1> -admin

user $

 ./bin/create-account --config dendrite.yaml --username <YourUsername2> --password <SecretPassword2>

Note
Including a white space before the command as shown in the example above will prevent the line from being recorded in bash's history file (~/.bash_history, which will help the passwords stay private.

Client

Connect to the home server using a web browser to manually trust the self-signed certificate. This avoids the need to put the self-signed certificate into a global trust, and adds it on a per-application basis.

Testing

curl (net-misc/curl) can be used to test the API from the command line for both self-signed and signed certificates. For example, to verify the dendrite server version:

user $curl --insecure https://dendrite.gentoo.test:8448/_matrix/federation/v1/version

{"server":{"version":"0.12.0","name":"Dendrite"}}

Troubleshooting

TLS handshake errors

Errors in the dendrite log like the following mean the self-signed test certificate is not trusted by the client:

 http: TLS handshake error from 1.2.3.4:59820: remote error: tls: unknown certificate

Either add the certificate to the client's trusted certificate store or temporary permit it in a web browser. See the Certificates article for more information pertaining to certificate management.

Synapse

Prerequisites

dev-python/virtualenv

Setup from source

Instructions for getting a basic Dendrite test server setup can be found upstream. Essentially:

Clone the code: git clone https://github.com/matrix-org/synapse
Create a python virtualenv and generate a configuration file.
Create a database.
- Verify correct settings in the /etc/conf.d/postgresql-13 file. By default the locale is C.UTF8 and text search configuration is English, which should be fine.
- Configure the server: emerge --config dev-db/postgresql
- Start the service:
  - systemd (optional) # systemctl enable --now postgresql-13
  - Manually start the service (optional):
    - sudo -u postgres bash
    - /usr/lib64/postgresql-13/bin/pg_ctl -D /var/lib/postgresql/13/data -l logfile start
- Create database user and database^[1]: sudo -u postgres bash
  - createuser --pwprompt synapse_user
  - psql
Configure a signed TLS certificate.
Start the home server.
Register a user^[2].
- register_new_matrix_user -c homeserver.yaml http://localhost:8008

To consider:

URL previews.

Test

user $curl --insecure http://localhost:8008/_matrix/federation/v1/version

{"server":{"name":"Synapse","version":"1.32.2"}}

Database maintenance

State table compressor

Clients

Some clients are being maintained in the matrix overlay other are in the guru overlay.

Prerequisite: app-eselect/eselect-repository

Install the overlay:

root #

eselect repository add matrix git https://anongit.gentoo.org/git/repo/proj/matrix.git

root #

emaint sync -r matrix

root #

eix-update # Regenerate eix database cache (optional)

weechat-matrix

Emerge dev-libs/olm (requires matrix overlay above):

root #emerge --ask dev-libs/olm

Manual installation (Python implementation)

Getting the weechat-matrix client (Python implementation) manually installed on Gentoo:

Prerequisites: dev-python/pip

user $

git clone https://github.com/poljar/weechat-matrix.git

user $

cd weechat-matrix

user $

pip install --user -r requirements.txt

user $

make install

The plugin should install to the current user's ~/.weechat/python directory as matrix.py.

On the weechat buffer, it is wise to restart weechat (using the /upgrade command works nicely), then attempt to load the plugin:

weechat

/upgrade

weechat

/script load matrix.py

python: loading script "/home/larry/.weechat/python/matrix.py"
python: registered script "matrix", version 0.2.0 (matrix chat plugin)
New key binding (context "cursor"): @chat(python.matrix.*):r => hsignal:matrix_cursor_reply

After the plugin has been successfully loaded, help can be obtained via:

weechat

/matrix help

Add custom server:

weechat

/matrix server add testservername testserver.org

weechat

/set matrix.server.testservername.username larry

weechat

/set matrix.server.testservername.password SeCrEtP@SsWoRd

weechat

/matrix connect testservername

Manual installation (Rust implementation)

Getting the weechat-matrix client (Rust implementation) manually installed on Gentoo:

Prerequisites: dev-lang/rust

user $

git clone https://github.com/poljar/weechat-matrix-rs.git

user $

cd weechat-matrix-rs

user $

cargo build

user $

make install

External references

https://brendan.abolivier.bzh/enter-the-matrix/ - Blog post reviewing and explaining the inner workings of Matrix.

[1] ttps://github.com/matrix-org/synapse/blob/develop/docs/postgres.md#set-up-database

[2] ttps://github.com/matrix-org/synapse/blob/develop/INSTALL.md#registering-a-user

[1]

[2]