Control, manage, provision and deploy matrix homeservers.
Project description
MatrixCtl
MatrixCtl is a simple, but feature-rich tool to remotely control, manage, provision and deploy your Matrix homeservers and users from your virtual terminal.
$ matrixctl
usage: matrixctl [-h] [--version] [-d] [-s SERVER] [-c CONFIG]
{adduser,adduser-jitsi,check,delroom,deluser,deluser-jitsi,deploy,get-event,get-events,joinroom,maintenance,purge-history,report,reports,rooms,server-notice,start,restart,stop,update,upload,user,users,version}
...
MatrixCtl is a simple, but feature-rich tool to remotely control, manage, provision and deploy Matrix homeservers.
positional arguments:
{adduser,adduser-jitsi,check,delroom,deluser,deluser-jitsi,deploy,get-event,get-events,joinroom,maintenance,purge-history,report,reports,rooms,server-notice,start,restart,stop,update,upload,user,users,version}
adduser Add a new matrix user
adduser-jitsi Add a new jitsi user
check Checks the deployment with ansible
delroom Deletes an empty room from the database
deluser Deletes a user
deluser-jitsi Deletes a jitsi user
deploy Provision and deploy
get-event get an event from the DB
get-events get user-events from the DB
joinroom Join a user to a room
maintenance Run maintenance tasks
purge-history Purge historic events from the DB
report Get an report event by report ID
reports Lists reported events
rooms List rooms
server-notice Send a server notice
start Starts all OCI containers
restart Restarts all OCI containers (alias for start)
stop Stops all OCI containers
update Updates the ansible repo
upload Upload a file.
user Get information about a specific user
users Lists users
version Get the version of the Synapse instance
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
-d, --debug Enables debugging mode.
-s SERVER, --server SERVER
Select the server. (default: "default")
-c CONFIG, --config CONFIG
A path to an alternative config file.
Thank you for using MatrixCtl!
Check out the docs: https://matrixctl.rtfd.io
Report bugs to: https://github.com/MichaelSasser/matrixctl/issues/new/choose
Installation
MatrixCtl is written in Python. The installation is straight forward. Just run
pip install matrixctl
. It will be installed from the
Python Package Index (PyPi).
Upgrade MatrixCtl with pip install --upgrade matrixctl
.
You will find more information in the documentation.
Documentation
The documentation is waiting for you, to check out.
Configuration File
To use this tool you need to have a configuration file in "~/.config/matrixctl/config.yaml" or in "/etc/matrixctl/config.yaml".
# Define your homeservers in "servers" here.
servers:
# Your default server. You can specify muliple servers here with arbitrary
# Names
default:
ansible:
# The absolute path to your playbook
playbook: /path/to/ansible/playbook
synapse:
# The absolute path to the synapse playbook.
# This is only used for updating the playbook.
playbook: /path/to/synapse/playbook
# If your matrix server is deployed, you may want to fill out the API section.
# It enables matrixctl to run more and faster commands. You can deploy and
# provision your Server without this section. You also can cerate a user with
# "matrixctl adduser --ansible YourUsername" and add your privileges after
# that.
api:
# Your domain should be something like "michaelsasser.org" without the
# "matrix." in the front. MatrixCtl will add that, if needed. An IP-Address
# is not enough.
domain: example.com
# The username your admin user
username: johndoe
# To use the API you need to have an administrator account. Enter your Token
# here. If you use the element client you will find it your user settings
# (click on your username on the upper left corner on your browser) in the
# "Help & About" tab. If you scroll down click next to "Access-Token:" on
# "<click to reveal>". It will be marked for you. Copy it in here.
token= "MyMatrixToken"
# In some cases, MatrixCtl does need to make many requests. To speed those
# requests a notch, you can set a concurrent_limit which is greater than
# one. This sets a limit to how many asynchronous workers can be spawned
# by MatrixCtl. If you set the number to high, MatrixCtl needs more time
# to spawn the workers, then a synchronous request would take.
concurrent_limit: 10
# Here you can add your SSH configuration.
ssh:
address: "matrix.{{ servers.default.api.domain }}" # With Jinja2 support
# The default port is 22. Can be omitted. Jinja2: "{{ default_ssh_port }}"
port: 22
# The default username is your current login name.
user: john
# Define your maintainance tasks
maintenance:
tasks:
- compress-state # Compress synapses state table
- vacuum # VACUUM the synapse database (garbage-collection)
# Another server.
foo:
# ...
server: # This is a reserved name, which cannot be used.
Predefined Jinja2 placeholders (all placeholders can be overwritten):
"{{ home }}"
-- The current users home path e.g./home/michael
,"{{ user }}"
-- The current users username e.g.michael
,"{{ default_ssh_port }}"
-- The default ssh port22
,"{{ default_api_concurrent_limit }}"
-- The default concurrent limit4
.
Check out the documentation for more information.
Discussions & Chat
If you have any thoughts or questions, you can ask them in the
discusions or in
the projects matrix room #matrixctl:matrix.org
.
Semantic Versioning and Branching Model
This Python package uses SemVer for its release cycle and the git-flow branching model (by Vincent Driessen).
It has two branches with infinite lifetime. The:
Contributing
Please check our Contributer Documentation.
License
Copyright © 2020-2001 Michael Sasser Info@MichaelSasser.org. Released under the GPLv3 license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for matrixctl-0.11.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d70d9625272876a5b7e70f9ce96a04b04a3b284201c258edc0bd8e6a3c9b0a3a |
|
MD5 | eee6cce5333347c924ecc355b1788ff8 |
|
BLAKE2b-256 | 06d817ab1660fac6c07e69014034444c849ff4191a4366f5e35423d8e9ab388f |