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.3.9 # 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.polylith.yaml dendrite.yaml

Edit the dendrite.yaml configuration file to include the domain name of the hosting server:

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: dendrite.gentoo.test

# Add all sqlite database connection_string subsections to use a local sqlite database.
# See: https://matrix-org.github.io/dendrite/installation/database#sqlite
# See: https://matrix-org.github.io/dendrite/installation/configuration#per-component-connections-all-other-configurations

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-monolith-server --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.3.9+397b158c","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: sudo -u postgres bash
    • createuser --pwprompt synapse_user
    • psql
• Configure a signed TLS certificate.
• Start the home server.
• Register a user.
  • 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.