diff --git a/CHANGELOG.md b/CHANGELOG.md index 6384a42b..140c4f70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +# 2020-07-22 + +## Synapse Admin support + +The playbook can now help you set up [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin). + +See our [Setting up Synapse Admin](docs/configuring-playbook-synapse-admin.md) documentation to get started. + + # 2020-07-20 ## matrix-reminder-bot support diff --git a/README.md b/README.md index 2cfbc6f2..f6daa129 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,8 @@ Using this playbook, you can get the following services configured on your serve - (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms +- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server + Basically, this playbook aims to get you up-and-running with all the basic necessities around Matrix, without you having to do anything else. **Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need. @@ -184,6 +186,8 @@ This playbook sets up your server using the following Docker images: - [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) - the [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) bot for one-off & recurring reminders and alarms (optional) +- [awesometechnologies/synapse-admin](https://hub.docker.com/r/awesometechnologies/synapse-admin) - the [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) web UI tool for administrating users and rooms on your Matrix server (optional) + ## Deficiencies diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md new file mode 100644 index 00000000..38162937 --- /dev/null +++ b/docs/configuring-playbook-synapse-admin.md @@ -0,0 +1,34 @@ +# Setting up Synapse Admin (optional) + +The playbook can install and configure [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) for you. + +It's a web UI tool you can use to **administrate users and rooms on your Matrix server**. + +See the project's [documentation](https://github.com/Awesome-Technologies/synapse-admin) to learn what it does and why it might be useful to you. + + +## Adjusting the playbook configuration + +Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: + +```yaml +matrix_synapse_admin_enabled: true +``` + + +## Installing + +After configuring the playbook, run the [installation](installing.md) command again: + +``` +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + + +## Usage + +After installation, Synapse Admin will be accessible at: `https://matrix.DOMAIN/synapse-admin/` + +To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server. + +The Homeserver URL to use on Synapse Admin's login page is: `https://matrix.DOMAIN` diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index 0c92be10..019a651f 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -16,3 +16,8 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you - or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml). - or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml). + + +## Synapse Admin + +Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md). diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 06657c70..3714247e 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -68,6 +68,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins ### Authentication and user-related +- [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional) + - [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced) - [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced) diff --git a/docs/registering-users.md b/docs/registering-users.md index 4bca71e8..09394450 100644 --- a/docs/registering-users.md +++ b/docs/registering-users.md @@ -35,3 +35,8 @@ The script `/usr/local/bin/matrix-change-user-admin-status` may be used to chang ``` /usr/local/bin/matrix-change-user-admin-status <0/1> ``` + + +## Managing users via a Web UI + +To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md). diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 5820b6b9..b81c87e9 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -1011,3 +1011,24 @@ matrix_synapse_systemd_wanted_services_list: | # /matrix-synapse # ###################################################################### + + + +###################################################################### +# +# matrix-synapse-admin +# +###################################################################### + +matrix_synapse_admin_enabled: false + +# Normally, matrix-nginx-proxy is enabled and nginx can reach Synapse Admin over the container network. +# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose +# Synapse Admin's HTTP port to the local host. +matrix_synapse_admin_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:8766' }}" + +###################################################################### +# +# /matrix-synapse-admin +# +###################################################################### diff --git a/roles/matrix-synapse-admin/defaults/main.yml b/roles/matrix-synapse-admin/defaults/main.yml new file mode 100644 index 00000000..01308d4a --- /dev/null +++ b/roles/matrix-synapse-admin/defaults/main.yml @@ -0,0 +1,25 @@ +# matrix-synapse-admin is a web UI for mananging the Synapse Matrix server +# See: https://github.com/Awesome-Technologies/synapse-admin + +matrix_synapse_admin_enabled: true + +matrix_synapse_admin_docker_image: "awesometechnologies/synapse-admin:0.4.1" +matrix_synapse_admin_docker_image_force_pull: "{{ matrix_synapse_admin_docker_image.endswith(':latest') }}" + +# A list of extra arguments to pass to the container +matrix_synapse_admin_container_extra_arguments: [] + +# List of systemd services that matrix-synapse-admin.service depends on +matrix_synapse_admin_systemd_required_services_list: ['docker.service'] + +# List of systemd services that matrix-synapse-admin.service wants +matrix_synapse_admin_systemd_wanted_services_list: [] + +# Controls whether the matrix-synapse-admin container exposes its HTTP port (tcp/80 in the container). +# +# Takes an ":" or "" value (e.g. "127.0.0.1:8766"), or empty string to not expose. +matrix_synapse_admin_container_http_host_bind_port: '' + +# The path at which Synapse Admin will be exposed on `matrix.DOMAIN` +# (only applies when matrix-nginx-proxy is used). +matrix_synapse_admin_public_endpoint: /synapse-admin diff --git a/roles/matrix-synapse-admin/tasks/init.yml b/roles/matrix-synapse-admin/tasks/init.yml new file mode 100644 index 00000000..1efba9a7 --- /dev/null +++ b/roles/matrix-synapse-admin/tasks/init.yml @@ -0,0 +1,50 @@ +- set_fact: + matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-synapse-admin'] }}" + when: matrix_synapse_admin_enabled|bool + +- block: + - name: Fail if matrix-nginx-proxy role already executed + fail: + msg: >- + Trying to append Synapse Admin's reverse-proxying configuration to matrix-nginx-proxy, + but it's pointless since the matrix-nginx-proxy role had already executed. + To fix this, please change the order of roles in your plabook, + so that the matrix-nginx-proxy role would run after the matrix-synapse-admin role. + when: matrix_nginx_proxy_role_executed|default(False)|bool + + - name: Generate Synapse Admin proxying configuration for matrix-nginx-proxy + set_fact: + matrix_synapse_admin_matrix_nginx_proxy_configuration: | + location ~ ^{{ matrix_synapse_admin_public_endpoint }}/?(.*) { + {% if matrix_nginx_proxy_enabled|default(False) %} + {# Use the embedded DNS resolver in Docker containers to discover the service #} + resolver 127.0.0.11 valid=5s; + set $backend "matrix-synapse-admin:80"; + proxy_pass http://$backend/$1; + {% else %} + {# Generic configuration for use outside of our container setup #} + proxy_pass http://127.0.0.1:8766/$1; + {% endif %} + } + + - name: Register Synapse Admin proxying configuration with matrix-nginx-proxy + set_fact: + matrix_nginx_proxy_proxy_matrix_additional_server_configuration_blocks: | + {{ + matrix_nginx_proxy_proxy_matrix_additional_server_configuration_blocks|default([]) + + + [matrix_synapse_admin_matrix_nginx_proxy_configuration] + }} + tags: + - always + when: matrix_synapse_admin_enabled|bool + +- name: Warn about reverse-proxying if matrix-nginx-proxy not used + debug: + msg: >- + NOTE: You've enabled the Synapse Admin tool but are not using the matrix-nginx-proxy + reverse proxy. + Please make sure that you're proxying the `{{ matrix_synapse_admin_public_endpoint }}` + URL endpoint to the matrix-synapse-admin container. + You can expose the container's port using the `matrix_synapse_admin_container_http_host_bind_port` variable. + when: "matrix_synapse_admin_enabled|bool and matrix_nginx_proxy_enabled is not defined" diff --git a/roles/matrix-synapse-admin/tasks/main.yml b/roles/matrix-synapse-admin/tasks/main.yml new file mode 100644 index 00000000..3763ba28 --- /dev/null +++ b/roles/matrix-synapse-admin/tasks/main.yml @@ -0,0 +1,8 @@ +- import_tasks: "{{ role_path }}/tasks/init.yml" + tags: + - always + +- import_tasks: "{{ role_path }}/tasks/setup.yml" + tags: + - setup-all + - setup-synapse-admin diff --git a/roles/matrix-synapse-admin/tasks/setup.yml b/roles/matrix-synapse-admin/tasks/setup.yml new file mode 100644 index 00000000..1e0cc471 --- /dev/null +++ b/roles/matrix-synapse-admin/tasks/setup.yml @@ -0,0 +1,60 @@ +--- + +# +# Tasks related to setting up matrix-synapse-admin +# + +- name: Ensure matrix-synapse-admin image is pulled + docker_image: + name: "{{ matrix_synapse_admin_docker_image }}" + source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}" + force_source: "{{ matrix_synapse_admin_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}" + force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_synapse_admin_docker_image_force_pull }}" + when: matrix_synapse_admin_enabled|bool + +- name: Ensure matrix-matrix-synapse-admin.service installed + template: + src: "{{ role_path }}/templates/systemd/matrix-synapse-admin.service.j2" + dest: "{{ matrix_systemd_path }}/matrix-synapse-admin.service" + mode: 0644 + register: matrix_synapse_admin_systemd_service_result + when: matrix_synapse_admin_enabled|bool + +- name: Ensure systemd reloaded after matrix-matrix-synapse-admin.service installation + service: + daemon_reload: yes + when: "matrix_synapse_admin_enabled|bool and matrix_synapse_admin_systemd_service_result.changed" + +# +# Tasks related to getting rid of matrix-synapse-admin (if it was previously enabled) +# + +- name: Check existence of matrix-matrix-synapse-admin service + stat: + path: "{{ matrix_systemd_path }}/matrix-matrix-synapse-admin.service" + register: matrix_synapse_admin_service_stat + +- name: Ensure matrix-matrix-synapse-admin is stopped + service: + name: matrix-matrix-synapse-admin + state: stopped + daemon_reload: yes + register: stopping_result + when: "not matrix_synapse_admin_enabled|bool and matrix_synapse_admin_service_stat.stat.exists" + +- name: Ensure matrix-matrix-synapse-admin.service doesn't exist + file: + path: "{{ matrix_systemd_path }}/matrix-matrix-synapse-admin.service" + state: absent + when: "not matrix_synapse_admin_enabled|bool and matrix_synapse_admin_service_stat.stat.exists" + +- name: Ensure systemd reloaded after matrix-matrix-synapse-admin.service removal + service: + daemon_reload: yes + when: "not matrix_synapse_admin_enabled|bool and matrix_synapse_admin_service_stat.stat.exists" + +- name: Ensure matrix-synapse-admin Docker image doesn't exist + docker_image: + name: "{{ matrix_synapse_admin_docker_image }}" + state: absent + when: "not matrix_synapse_admin_enabled|bool" diff --git a/roles/matrix-synapse-admin/templates/systemd/matrix-synapse-admin.service.j2 b/roles/matrix-synapse-admin/templates/systemd/matrix-synapse-admin.service.j2 new file mode 100644 index 00000000..7c767886 --- /dev/null +++ b/roles/matrix-synapse-admin/templates/systemd/matrix-synapse-admin.service.j2 @@ -0,0 +1,40 @@ +#jinja2: lstrip_blocks: "True" +[Unit] +Description=matrix-synapse-admin +{% for service in matrix_synapse_admin_systemd_required_services_list %} +Requires={{ service }} +After={{ service }} +{% endfor %} +{% for service in matrix_synapse_admin_systemd_wanted_services_list %} +Wants={{ service }} +{% endfor %} + +[Service] +Type=simple +ExecStartPre=-{{ matrix_host_command_docker }} kill matrix-synapse-admin +ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-synapse-admin + +ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-synapse-admin \ + --log-driver=none \ + --cap-drop=ALL \ + --cap-add=CAP_CHOWN \ + --cap-add=CAP_NET_BIND_SERVICE \ + --cap-add=CAP_SETUID \ + --cap-add=CAP_SETGID \ + --network={{ matrix_docker_network }} \ + {% if matrix_synapse_admin_container_http_host_bind_port %} + -p {{ matrix_synapse_admin_container_http_host_bind_port }}:80 \ + {% endif %} + {% for arg in matrix_synapse_admin_container_extra_arguments %} + {{ arg }} \ + {% endfor %} + {{ matrix_synapse_admin_docker_image }} + +ExecStop=-{{ matrix_host_command_docker }} kill matrix-synapse-admin +ExecStop=-{{ matrix_host_command_docker }} rm matrix-synapse-admin +Restart=always +RestartSec=30 +SyslogIdentifier=matrix-synapse-admin + +[Install] +WantedBy=multi-user.target diff --git a/setup.yml b/setup.yml index ea5212a6..1c19d442 100755 --- a/setup.yml +++ b/setup.yml @@ -25,6 +25,7 @@ - matrix-bridge-sms - matrix-bot-matrix-reminder-bot - matrix-synapse + - matrix-synapse-admin - matrix-client-element - matrix-jitsi - matrix-ma1sd