From Gentoo Wiki
Jump to:navigation Jump to:search

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


  • 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


Project links


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




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

user $git clone
user $cd dendrite
user $git checkout v0.3.9 # Checkout the latest tagged release
user $./
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.
 # 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:
# See:

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 -https-bind-address

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>
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.


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.


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


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 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.



Setup from source

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

  • Clone the code: git clone
  • 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].

To consider:


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

Database maintenance


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
root #emaint sync -r matrix
root #eix-update # Regenerate eix database cache (optional)


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
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

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

weechat/script load
python: loading script "/home/larry/.weechat/python/"
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
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
user $cd weechat-matrix-rs
user $cargo build
user $make install

External references