MatrixCtl documentation

MatrixCtl is a python program to control, manage, provision and deploy our matrix homeserver. I had a bunch of shell scripts doing that. Two weeks after using them I couldn’t remember the order in which I have to use the arguments or which arguments where needed. It was a pain. So I decided I hack something together fast.

It’s not the most elegant piece of software I wrote, but it should do the trick. I will continue to port the rest of the scripts and add new features.

Contents:

Branching Model

This repository uses the GitHub Flow.

Command line tool

MatrixCtl as a pure commandline tool. You can use it as package, if you like, but breaking changes may introduced, even in a minor change.

Traceback (most recent call last):
  File "/home/docs/.asdf/installs/python/3.10.17/lib/python3.10/runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/home/docs/.asdf/installs/python/3.10.17/lib/python3.10/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/matrixctl/checkouts/stable/docs/source/../../src/matrixctl/__main__.py", line 28, in <module>
    import coloredlogs
ModuleNotFoundError: No module named 'coloredlogs'

Configuration File

To use this program you need to have this config file in /etc/matrixctl/config or in ~/.config/matrixctl/config.

 1# Define your homeservers in "servers" here.
 2servers:
 3    # Your default server. You can specify muliple servers here with arbitrary
 4    # Names
 5  default:
 6
 7    ansible:
 8      # The absolute path to your playbook
 9      playbook: /path/to/ansible/playbook
10
11    synapse:
12      # The absolute path to the synapse playbook.
13      # This is only used for updating the playbook.
14      playbook: /path/to/synapse/playbook
15
16    # If your matrix server is deployed, you may want to fill out the API section.
17    # It enables matrixctl to run more and faster commands. You can deploy and
18    # provision your Server without this section. You also can create a user with
19    # "matrixctl adduser --ansible YourUsername" and add your privileges after
20    # that.
21    api:
22      # Your domain should be something like "michaelsasser.org" without the
23      # "matrix." in the front. MatrixCtl will add that, if needed. An IP-Address
24      # is not enough.
25      domain: example.com
26
27      # The username your admin user
28      username: johndoe
29
30      # To use the API you need to have an administrator account. Enter your Token
31      # here. If you use the element client you will find it your user settings
32      # (click on your username on the upper left corner on your browser) in the
33      # "Help & About" tab. If you scroll down click next to "Access-Token:" on
34      # "<click to reveal>". It will be marked for you. Copy it in here.
35      token: "MyMatrixToken"
36
37      # In some cases, MatrixCtl does need to make many requests. To speed those
38      # requests a notch, you can set a concurrent_limit which is greater than
39      # one. This sets a limit to how many asynchronous workers can be spawned
40      # by MatrixCtl. If you set the number to high, MatrixCtl needs more time
41      # to spawn the workers, then a synchronous request would take.
42      concurrent_limit: 10
43
44    # Here you can add your SSH configuration.
45    ssh:
46      address: matrix.example.com
47
48      # The default port is 22
49      port: 22
50
51      # The default username is your current login name.
52      user: john
53
54    # Define your maintenance tasks
55    maintenance:
56      tasks:
57        - compress-state  # Compress synapses state table
58        - vacuum          # VACUUM the synapse database (garbage-collection)
59
60    # Add connection parameters to the Database
61    # Synapse does only read (SELECT) information from the database.
62    # The user needs to be able to login to the synapse database
63    # and SELECT from the events and event_json tables.
64    database:
65      synapse_database: synapse  # this is the playbooks default table name
66      synapse_user: matrixctl    # the username (role) for the database
67      synapse_password: "RolePassword"
68      tunnel: true        # true if an ssh tunnel should be used to connect
69
70      # The port that was used in the playbook  (e.g.
71      # matrix_postgres_container_postgres_bind_port: 5432)
72      # or for your external database. For security reasons the port
73      # should be blocked by your firewall. Iy you enable the tunnel
74      # by setting tunnel: true, MatrixCtl activates a SSH tunnel.
75      port: 5432          # the remote port
76
77  # Another server.
78  foo:
79    # ...

PyPA Versioning

This repository uses PyPA for its release cycle.

Indices and tables

License

Copyright © 2020 Michael Sasser <Info@MichaelSasser.org>. Released under the GPLv3 license.