Skip to content
This repository was archived by the owner on Apr 4, 2025. It is now read-only.

README rewrite (v2) #146

Draft
JacksonChen666 wants to merge 9 commits into
base: master
Choose a base branch
from
Draft

README rewrite (v2) #146

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
97be146
remove extra newlines
JacksonChen666 May 30, 2024
deabff7
remove git installation method from README
JacksonChen666 May 30, 2024
e75e740
move upgrading near installation
JacksonChen666 May 30, 2024
334230d
lots of rewording
JacksonChen666 May 30, 2024
82c2f58
move getting admin token down
JacksonChen666 May 30, 2024
a9f1078
reword in install section
JacksonChen666 May 30, 2024
0a2641d
TODO add other install methods link
JacksonChen666 May 30, 2024
60aafc4
rename "get in touch" to "support"
JacksonChen666 May 30, 2024
ff2cdcf
Apply suggestions from code review
JacksonChen666 Aug 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 28 additions & 106 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,21 @@
- [About](#about)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Install from PyPI](#install-from-pypi)
- [Install from git](#install-from-git)
- [Update](#update)
- [Configuration](#configuration)
- [Getting an Admin Token](#getting-an-admin-token)
- [The configurator](#the-configurator)
- [Getting an Admin Token](#getting-an-admin-token)
- [matrix-docker-ansible-deploy](#matrix-docker-ansible-deploy)
- [Usage](#usage)
- [Command Line Reference](#command-line-reference)
- [Advanced Usage](#advanced-usage)
- [Update](#update)
- [Update PyPI Package](#update-pypi-package)
- [Update git Installation](#update-git-installation)
- [Implementation Status / Commands List](#implementation-status--commands-list)
- [Get in Touch](#get-in-touch)
- [Support](#support)
- [Contributing](#contributing)




## About

A CLI tool to help admins of [Matrix-Synapse homeservers](https://github.com/matrix-org/synapse) conveniently issue commands available via its [Admin API](https://element-hq.github.io/synapse/develop/usage/administration/admin_api/index.html#the-admin-api).


A CLI tool for the [Synapse Admin API](https://element-hq.github.io/synapse/develop/usage/administration/admin_api/index.html#the-admin-api).

## Prerequisites

Expand All @@ -36,67 +27,45 @@ A CLI tool to help admins of [Matrix-Synapse homeservers](https://github.com/mat
- an admin-enabled user on the instance
- the admin user's access token

`synadm` is designed to run either directly on the host running the Synapse instance or on a remote machine able to access Synapse's API port. Synapse's default Admin API endpoint address usually is http://localhost:8008/_synapse/admin or https://localhost:8448/_synapse/admin.



`synadm` is designed to run either directly on the host running the Synapse instance or on a remote machine able to access Synapse's API port. Synapse's default Admin API endpoint address usually is `http://localhost:8008/_synapse/admin` or `https://localhost:8448/_synapse/admin`.

## Installation

### Install from PyPI
To install synadm from PyPI, run the following command:

`pip3 install synadm`

### Install from git
Other installation methods: [Install via git](TODO)

<!-- omit in toc -->
#### 1. Check Python Version
## Update

`python3 --version` should show at least v3.6.x

<!-- omit in toc -->
#### 2. Clone Repo:
If you already have synadm installed from the PyPI, run this to upgrade synadm to a new release:

```
git clone https://github.com/joj0/synadm
pip3 install synadm --upgrade
```

<!-- omit in toc -->
#### 3. Install Package Globally

This will install `synadm` and all dependent Python packages to your system's global Python site-packages directory:

```
cd synadm
sudo pip install .
```
## Configuration

*Note: If you get an import error for setuptools, make sure the package is installed. Debian based systems: `sudo apt install python3-setuptools`, RedHat based: `sudo yum install python3-setuptools`*
### The configurator

<!-- omit in toc -->
#### 4. Run
`synadm` asks for necessary configuration items on first launch automatically. Also whenever new mandatory configuration items where added (eg after an update), the user will be prompted for missing items automatically.

`synadm` should now run fine without having to add a path in front of it:
Configuration can be changed any time by launching the configurator directly:

```
synadm -h
synadm config
```

*Note: Usually setuptools installs a command wrapper to `/usr/local/bin/synadm`, but that depends on your system.*

*Note: In case you don't want `synadm` to be installed to a global system directory, you can find an [alternative way of installing](CONTRIBUTING.md#getting-the-source--installing) in the contribution docs*.

*Note: synadm is multi-user aware - it stores its configuration inside the executing user's home directory. See chapter [configuration](#configuration).*


Configuration will be saved in `~/.config/synadm.yaml`

## Configuration
*Note: Be aware that once you configured `synadm`, your admin user's token is saved in the configuration file. On Posix compatible systems permissions are set to mode 0600, on other OS's it is your responsibilty to change permissions accordingly.*

### Getting an Admin Token

To find out your admin user's token in Element-Web: _Login as this user - "Click User Avatar" - "All Settings" - "Help & About" - Scroll down - "Advanced" - "Access Token"_

Or use synadm to fetch a token already. Use the fully qualified Matrix ID of the admin user:
You can also use synadm to fetch a token by logging in. Use the fully qualified Matrix ID of the admin user:

```
synadm matrix login @admin_username:yourdomain.org
Expand All @@ -109,21 +78,6 @@ If you issue this command in a fresh `synadm` installation, [the configurator](#
- Set token to "invalid" at first, to convience `synadm` to launch the `matrix login` command (otherwise you'd get a "Configuration incomplete" error).
- After successfully entering your admin password you will be presented a token which you can finally set by re-launching the configurator as described below.

### The configurator

`synadm` asks for necessary configuration items on first launch automatically. Also whenever new mandatory configuration items where added (eg after an update), the user will be prompted for missing items automatically.

Configuration can be changed any time by launching the configurator directly:

```
synadm config
```

Configuration will be saved in `~/.config/synadm.yaml`


*Note: Be aware that once you configured `synadm`, your admin user's token is saved in the configuration file. On Posix compatible systems permissions are set to mode 0600, on other OS's it is your responsibilty to change permissions accordingly.*

### matrix-docker-ansible-deploy

To use `synadm` with Synapse homeservers that were installed using [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) you have two options.
Expand All @@ -150,22 +104,22 @@ Find more details about the topic [here](https://github.com/spantaleev/matrix-do

## Usage

Use the online help of the main command:
Get help information for the top level commands by running:

```
synadm -h
```

and of the available subcommands:
Similar to subcommands:

```
synadm version -h
synadm user -h
synadm room -h
```

You even can spare the `-h` option, `synadm` will show some abbreviated help for the executed subcommand anyway. For example:

For commands with subcommands, help will be shown by default when running
something like:
```
synadm user
```
Expand All @@ -174,53 +128,25 @@ or
synadm user details
```

will show essential help for the particular subcommand right away.

*Note: A list of currently available commands is found in chapter [implementation status / commands list](#implementation-status--commands-list)* as well as in the following chapter.

### Command Line Reference

A detailed [Command Line Reference](https://synadm.readthedocs.io/en/latest/index_cli_reference.html) can be found in `synadm's` readthedocs documentation.


### Advanced Usage

Examples of how `synadm` can be used in shell scripts and oneliners is
provided in the
[Scripting Examples](https://synadm.readthedocs.io/en/latest/examples.html)
docs chapter.

## Update

### Update PyPI Package

```
pip3 install synadm --upgrade
```

### Update git Installation

To update `synadm` to the latest development state, just update your git repo and reinstall:

```
cd synadm
git pull
pip install .
```

*Note: If you installed it to a Python venv, [activate it](CONTRIBUTING.md#3-set-up-a-python3-virtual-environment).*

*Note: If you installed it in [editable mode](CONTRIBUTING.md#4-install-in-editable-mode) (or for development), you can spare the `pip install .` command - just `git pull` and you're done.*



## Implementation Status / Commands List

[Follow this link to the official Synapse Admin API docs](https://element-hq.github.io/synapse/develop/usage/administration/admin_api/index.html) - direct links to the specific API documentation pages are provided in the list below.

*Note: Most commands have several optional arguments available. Put -h after any of the below listed commands to view them or have a look at the [Command Line Reference](https://synadm.readthedocs.io/en/latest/index_cli_reference.html).*


* [ ] [Account Validity](https://element-hq.github.io/synapse/develop/admin_api/account_validity.html)
* [x] [Delete Group](https://element-hq.github.io/synapse/develop/admin_api/delete_group.html) (delete community)
* [ ] [Event Reports](https://element-hq.github.io/synapse/develop/admin_api/event_reports.html)
Expand Down Expand Up @@ -283,22 +209,18 @@ pip install .
* [x] `regtok update <registration token>`
* [x] `regtok delete <registration token>`

## Support

If you need help with using `synadm`, have a feature idea or would like to discuss anything else around `synadm`, get in touch via [our Matrix room][synadmroom]!

## Get in Touch

If you need advice on using synadm, have a feature idea or would like to discuss anything else around `synadm`, get in touch via Matrix!

We are hanging around in the official support room for Synapse, [#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org). Usually you'll find `synadm` users there that might answer your questions already. If not, mentioning `synadm` will ping us with the help of Element's keyword notify feature and we'll try to get in touch.

The most direct way to reach synadm maintainers as well as seasoned users and Synapse admins is by joining [#synadm:peek-a-boo.at](https://matrix.to/#/#synadm:peek-a-boo.at).

If you are sure you've found a bug that was not already reported, certainly directly opening an [issue on GitHub](https://github.com/JOJ0/synadm/issues) is a valid option too. If unsure, ask in [#synadm:peek-a-boo.at](https://matrix.to/#/#synadm:peek-a-boo.at) first.
If you have questions about Synapse (the homeserver), you should join [the room for Synapse](https://matrix.to/#/#synapse:matrix.org). That room should help you better answer Synapse questions.

If you are sure you've found a bug that was not already reported, opening an [issue on GitHub](https://github.com/JOJ0/synadm/issues) is a valid option too. If unsure, ask in [#synadm:peek-a-boo.at][synadmroom] first.

[synadmroom]:https://matrix.to/#/#synadm:peek-a-boo.at

## Contributing

First of all, thanks for your interest in contributing to `synadm`! We appreciate any help, no matter if you are a programmer or a user. Both groups can do valuable things for the `synadm` project. We love providing a useful tool to fellow Synapse sysadmins but rely on contribution from the Synapse and Matrix community to keep `synadm` useful, current and stable.
First of all, thanks for your interest in contributing to `synadm`! We appreciate any help, no matter if you are a programmer or a user.

Please review the [contributing docs](CONTRIBUTING.md) for guidelines and help around the topic!