{"id":17308983,"url":"https://github.com/michaelsasser/matrixctl","last_synced_at":"2025-04-12T19:53:16.457Z","repository":{"id":36976378,"uuid":"253392316","full_name":"MichaelSasser/matrixctl","owner":"MichaelSasser","description":"Control, manage, provision and deploy your matrix homeserver.","archived":false,"fork":false,"pushed_at":"2025-04-07T01:32:48.000Z","size":11700,"stargazers_count":11,"open_issues_count":10,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T19:53:10.701Z","etag":null,"topics":["ansible","api","deployment","matrix","matrix-homeserver","provision","pypi","python","semver"],"latest_commit_sha":null,"homepage":"https://matrixctl.rtfd.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MichaelSasser.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-06T04:15:01.000Z","updated_at":"2025-04-07T01:32:30.000Z","dependencies_parsed_at":"2024-06-05T20:06:42.893Z","dependency_job_id":"b1018ca6-c982-4887-bcb4-21148b67a0d4","html_url":"https://github.com/MichaelSasser/matrixctl","commit_stats":{"total_commits":762,"total_committers":7,"mean_commits":"108.85714285714286","dds":0.547244094488189,"last_synced_commit":"54dab054df6284d9f9b480c10bbdac5a39f74500"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSasser%2Fmatrixctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSasser%2Fmatrixctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSasser%2Fmatrixctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSasser%2Fmatrixctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichaelSasser","download_url":"https://codeload.github.com/MichaelSasser/matrixctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625509,"owners_count":21135513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","api","deployment","matrix","matrix-homeserver","provision","pypi","python","semver"],"created_at":"2024-10-15T12:07:28.146Z","updated_at":"2025-04-12T19:53:16.432Z","avatar_url":"https://github.com/MichaelSasser.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub](https://img.shields.io/github/license/MichaelSasser/matrixctl?style=flat-square)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/matrixctl?style=flat-square)\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/michaelsasser/matrixctl?style=flat-square)\n![GitHub Release Date](https://img.shields.io/github/release-date/michaelsasser/matrixctl?style=flat-square)\n![Matrix](https://img.shields.io/matrix/matrixctl:matrix.org?server_fqdn=matrix.org\u0026style=flat-square)\n\n# MatrixCtl\n\nMatrixCtl is a simple, but feature-rich tool to remotely control, manage,\nprovision and deploy your Matrix homeservers right from your virtual terminal.\n\n```console\nusage: matrixctl [-h] [--version] [-d] [-s SERVER] [-c CONFIG] Command ...\n\nMatrixCtl is a simple, but feature-rich tool to remotely control, manage, provision and deploy Matrix homeservers.\n\noptions:\n  -h, --help            show this help message and exit\n  --version             show program's version number and exit\n  -d, --debug           Enables debugging mode.\n  -s, --server SERVER   Select the server. (default: \"default\")\n  -c, --config CONFIG   A path to an alternative config file.\n\nCommands:\n  The following are commands, you can use to accomplish various tasks.\n\n  Command\n    adduser             Add users to the homeserver\n    check               Checks the deployment with Ansible\n    delete-local-media  Delete cached (local) media that was last accessed before a specific point in time\n    delroom             Shutdown a room\n    deluser             Deactivate users\n    deploy              Provision and deploy the Ansible playbook\n    download            Download a media file.\n    get-event           Get an event from the database\n    get-event-context   Get the context of an event\n    get-events          Get events from the database\n    is-admin            Check, if a user is a homeserver administrator\n    joinroom            Join a user to a room\n    largest-rooms       List an approximation of the 10 largest rooms in the database\n    maintenance         Run maintenance tasks\n    make-room-admin     Grant a user the highest power level available to a local user in this room\n    purge-history       Purge historic events from the database\n    purge-remote-media  Purge cached, remote media\n    report              Get a report event by report identifier\n    reports             Lists reported events\n    rooms               List rooms\n    server-notice       Send a server notice to a user\n    set-admin           Change whether a user is a homeserver admin or not\n    start               Starts all OCI containers\n    restart             Restarts all OCI containers (alias for start)\n    stop                Stop and disable all OCI containers\n    update              Updates the ansible playbook repository\n    upload              Upload a media file.\n    user                Get information about a specific user\n    users               Lists all users of the homeserver\n    version             Get the version information of the Synapse instance\n\nThank you for using MatrixCtl!\nCheck out the docs: https://matrixctl.rtfd.io\nReport bugs to: https://github.com/MichaelSasser/matrixctl/issues/new/choose\n```\n\n## Installation\n\nMatrixCtl is written in Python. The installation is straight forward. Just run\n`pip install matrixctl`. It will be installed from the\n[Python Package Index (PyPi)](https://pypi.org/project/matrixctl/).\n\nUpgrade MatrixCtl with `pip install --upgrade matrixctl`.\n\nYou will find more information in the\n[documentation](https://matrixctl.readthedocs.io/en/latest/installation.html).\n\n## Documentation\n\nThe [documentation](https://matrixctl.readthedocs.io/en/latest/index.html) is\nwaiting for you, to check out.\n\n## Configuration File\n\nTo use this tool you need to have a configuration file in\n\"~/.config/matrixctl/config.yaml\" or in \"/etc/matrixctl/config.yaml\".\n\n```yaml\n# Define your homeservers in \"servers\" here.\nservers:\n  # Your default server. You can specify muliple servers here with arbitrary\n  # Names\n  default:\n    ansible:\n      # The absolute path to your playbook\n      playbook: /path/to/ansible/playbook\n\n    synapse:\n      # The absolute path to the synapse playbook.\n      # This is only used for updating the playbook.\n      playbook: /path/to/synapse/playbook\n\n    # If your matrix server is deployed, you may want to fill out the API section.\n    # It enables matrixctl to run more and faster commands. You can deploy and\n    # provision your Server without this section. You also can create a user with\n    # \"matrixctl adduser --ansible YourUsername\" and add your privileges after\n    # that.\n    api:\n      # Your domain should be something like \"michaelsasser.org\" without the\n      # \"matrix.\" in the front. MatrixCtl will add that, if needed. An IP-Address\n      # is not enough.\n      domain: example.com\n\n      # The username your admin user\n      username: johndoe\n\n      # To use the API you need to have an administrator account. Enter your Token\n      # here. If you use the element client you will find it your user settings\n      # (click on your username on the upper left corner on your browser) in the\n      # \"Help \u0026 About\" tab. If you scroll down click next to \"Access-Token:\" on\n      # \"\u003cclick to reveal\u003e\". It will be marked for you. Copy it in here.\n      token: \"MyMatrixToken\"\n\n      # In some cases, MatrixCtl does need to make many requests. To speed those\n      # requests a notch, you can set a concurrent_limit which is greater than\n      # one. This sets a limit to how many asynchronous workers can be spawned\n      # by MatrixCtl. If you set the number to high, MatrixCtl needs more time\n      # to spawn the workers, then a synchronous request would take.\n      concurrent_limit: 10\n\n    # Here you can add your SSH configuration.\n    ssh:\n      address: matrix.example.com\n\n      # The default port is 22\n      port: 22\n\n      # The default username is your current login name.\n      user: john\n\n    # Define your maintenance tasks\n    maintenance:\n      tasks:\n        - compress-state # Compress synapses state table\n        - vacuum # VACUUM the synapse database (garbage-collection)\n\n    # Add connection parameters to the Database\n    # Synapse does only read (SELECT) information from the database.\n    # The user needs to be able to login to the synapse database\n    # and SELECT from the events and event_json tables.\n    database:\n      synapse_database: synapse # this is the playbooks default table name\n      synapse_user: matrixctl # the username (role) for the database\n      synapse_password: \"RolePassword\"\n      tunnel: true # true if an ssh tunnel should be used to connect\n\n      # The port that was used in the playbook  (e.g.\n      # matrix_postgres_container_postgres_bind_port: 5432)\n      # or for your external database. For security reasons the port\n      # should be blocked by your firewall. Iy you enable the tunnel\n      # by setting tunnel: true, MatrixCtl activates a SSH tunnel.\n      port: 5432 # the remote port\n\n  # Another server.\n  foo:\n    # ...\n```\n\nPredefined Jinja2 placeholders (all placeholders can be overwritten):\n\n- `\"{{ home }}\"` -- The current users home path e.g. `/home/michael`,\n- `\"{{ user }}\"` -- The current users username e.g. `michael`,\n- `\"{{ default_ssh_port }}\"` -- The default ssh port `22`,\n- `\"{{ default_api_concurrent_limit }}\"` -- The default concurrent limit `4`.\n\nCheck out the\n[documentation](https://matrixctl.readthedocs.io/en/latest/getting_started/config_file.html)\nfor more information.\n\n## Discussions \u0026 Chat\n\nIf you have any thoughts or questions, you can ask them in the\n[discusions](https://github.com/MichaelSasser/matrixctl/discussions) or in the\nprojects matrix room `#matrixctl:matrix.org`.\n\n## Versioning and Branching Model\n\nThis Python package follows the\n[PyPA](https://packaging.python.org/en/latest/specifications/) specification\nfor its release cycle and follows the\n[GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow).\n\n## Contributing\n\nPlease check our\n[Contributer Documentation](https://matrixctl.readthedocs.io/en/latest/contributer_documentation/index.html#contributer-documentation).\n\n## License\n\nCopyright \u0026copy; 2020-2024 Michael Sasser \u003cInfo@MichaelSasser.org\u003e. Released\nunder the GPLv3 license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelsasser%2Fmatrixctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaelsasser%2Fmatrixctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelsasser%2Fmatrixctl/lists"}