mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-06-30 05:07:50 +02:00
merge upstream
This commit is contained in:
Michael
@ -34,6 +34,7 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco
|
||||
| CNAME | `dimension` (*) | - | - | - | `matrix.<your-domain>` |
|
||||
| CNAME | `jitsi` (*) | - | - | - | `matrix.<your-domain>` |
|
||||
| CNAME | `stats` (*) | - | - | - | `matrix.<your-domain>` |
|
||||
| CNAME | `goneb` (*) | - | - | - | `matrix.<your-domain>` |
|
||||
|
||||
## Subdomains setup
|
||||
|
||||
@ -48,6 +49,8 @@ The `jitsi.<your-domain>` subdomain may be necessary, because this playbook coul
|
||||
|
||||
The `stats.<your-domain>` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.<your-domain>` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.<your-domain>` subdomain.
|
||||
|
||||
The `goneb.<your-domain>` subdomain may be necessary, because this playbook could install the [Go-NEB](https://github.com/matrix-org/go-neb) bot. The installation of Go-NEB is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Go-NEB guide](configuring-playbook-bot-go-neb.md). If you do not wish to set up Go-NEB, feel free to skip the `goneb.<your-domain>` DNS record.
|
||||
|
||||
|
||||
## `_matrix-identity._tcp` SRV record setup
|
||||
|
||||
|
||||
226
docs/configuring-playbook-bot-go-neb.md
Normal file
226
docs/configuring-playbook-bot-go-neb.md
Normal file
@ -0,0 +1,226 @@
|
||||
# Setting up Go-NEB (optional)
|
||||
|
||||
The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
|
||||
|
||||
Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Registering the bot user
|
||||
|
||||
The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
|
||||
|
||||
You **need to register the bot user manually** before setting up the bot.
|
||||
|
||||
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
|
||||
|
||||
You can use the playbook to [register a new user](registering-users.md):
|
||||
|
||||
```
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
|
||||
```
|
||||
|
||||
|
||||
## Getting an access token
|
||||
|
||||
If you use curl, you can get an access token like this:
|
||||
|
||||
```
|
||||
curl -X POST --header 'Content-Type: application/json' -d '{
|
||||
"identifier": { "type": "m.id.user", "user": "bot.go-neb" },
|
||||
"password": "a strong password",
|
||||
"type": "m.login.password"
|
||||
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
|
||||
```
|
||||
|
||||
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
matrix_bot_go_neb_enabled: true
|
||||
|
||||
# You need at least 1 client.
|
||||
# Use the access token you obtained in the step above.
|
||||
matrix_bot_go_neb_clients:
|
||||
- UserID: "@goneb:{{ matrix_domain }}"
|
||||
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
|
||||
DeviceID: "DEVICE1"
|
||||
HomeserverURL: "{{ matrix_homeserver_container_url }}"
|
||||
Sync: true
|
||||
AutoJoinRooms: true
|
||||
DisplayName: "Go-NEB!"
|
||||
AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
|
||||
|
||||
- UserID: "@another_goneb:{{ matrix_domain }}"
|
||||
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
|
||||
DeviceID: "DEVICE2"
|
||||
HomeserverURL: "{{ matrix_homeserver_container_url }}"
|
||||
Sync: false
|
||||
AutoJoinRooms: false
|
||||
DisplayName: "Go-NEB!"
|
||||
AcceptVerificationFromUsers: ["^@admin:{{ matrix_domain }}"]
|
||||
|
||||
# Optional, for use with the github_cmd, github_webhooks or jira services
|
||||
matrix_bot_go_neb_realms:
|
||||
- ID: "github_realm"
|
||||
Type: "github"
|
||||
Config: {} # No need for client ID or Secret as Go-NEB isn't generating OAuth URLs
|
||||
|
||||
# Optional. The list of *authenticated* sessions which Go-NEB is aware of.
|
||||
matrix_bot_go_neb_sessions:
|
||||
- SessionID: "your_github_session"
|
||||
RealmID: "github_realm"
|
||||
UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
|
||||
Config:
|
||||
# Populate these fields by generating a "Personal Access Token" on github.com
|
||||
AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
|
||||
Scopes: "admin:org_hook,admin:repo_hook,repo,user"
|
||||
|
||||
# The list of services which Go-NEB is aware of.
|
||||
# Delete or modify this list as appropriate.
|
||||
# See the docs for /configureService for the full list of options:
|
||||
# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
|
||||
# You need at least 1 service.
|
||||
matrix_bot_go_neb_services:
|
||||
- ID: "echo_service"
|
||||
Type: "echo"
|
||||
UserID: "@goneb:{{ matrix_domain }}"
|
||||
Config: {}
|
||||
|
||||
# Can be obtained from https://developers.giphy.com/dashboard/
|
||||
- ID: "giphy_service"
|
||||
Type: "giphy"
|
||||
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
|
||||
Config:
|
||||
api_key: "qwg4672vsuyfsfe"
|
||||
use_downsized: false
|
||||
|
||||
# This service has been dead for over a year :/
|
||||
- ID: "guggy_service"
|
||||
Type: "guggy"
|
||||
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
|
||||
Config:
|
||||
api_key: "2356saaqfhgfe"
|
||||
|
||||
# API Key via https://developers.google.com/custom-search/v1/introduction
|
||||
# CX via http://www.google.com/cse/manage/all
|
||||
# https://stackoverflow.com/questions/6562125/getting-a-cx-id-for-custom-search-google-api-python
|
||||
# 'Search the entire web' and 'Image search' enabled for best results
|
||||
- ID: "google_service"
|
||||
Type: "google"
|
||||
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
|
||||
Config:
|
||||
api_key: "AIzaSyA4FD39m9"
|
||||
cx: "AIASDFWSRRtrtr"
|
||||
|
||||
# Get a key via https://api.imgur.com/oauth2/addclient
|
||||
# Select "oauth2 without callback url"
|
||||
- ID: "imgur_service"
|
||||
Type: "imgur"
|
||||
UserID: "@imgur:{{ matrix_domain }}" # requires a Syncing client
|
||||
Config:
|
||||
client_id: "AIzaSyA4FD39m9"
|
||||
client_secret: "somesecret"
|
||||
|
||||
- ID: "wikipedia_service"
|
||||
Type: "wikipedia"
|
||||
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
|
||||
Config:
|
||||
|
||||
- ID: "rss_service"
|
||||
Type: "rssbot"
|
||||
UserID: "@another_goneb:{{ matrix_domain }}"
|
||||
Config:
|
||||
feeds:
|
||||
"http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
|
||||
rooms: ["!qmElAGdFYCHoCJuaNt:{{ matrix_domain }}"]
|
||||
must_include:
|
||||
author:
|
||||
- author1
|
||||
description:
|
||||
- lorem
|
||||
- ipsum
|
||||
must_not_include:
|
||||
title:
|
||||
- Lorem
|
||||
- Ipsum
|
||||
|
||||
- ID: "github_cmd_service"
|
||||
Type: "github"
|
||||
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
|
||||
Config:
|
||||
RealmID: "github_realm"
|
||||
|
||||
# Make sure your BASE_URL can be accessed by Github!
|
||||
- ID: "github_webhook_service"
|
||||
Type: "github-webhook"
|
||||
UserID: "@another_goneb:{{ matrix_domain }}"
|
||||
Config:
|
||||
RealmID: "github_realm"
|
||||
ClientUserID: "@YOUR_USER_ID:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
|
||||
Rooms:
|
||||
"!someroom:id":
|
||||
Repos:
|
||||
"matrix-org/synapse":
|
||||
Events: ["push", "issues"]
|
||||
"matrix-org/dendron":
|
||||
Events: ["pull_request"]
|
||||
"!anotherroom:id":
|
||||
Repos:
|
||||
"matrix-org/synapse":
|
||||
Events: ["push", "issues"]
|
||||
"matrix-org/dendron":
|
||||
Events: ["pull_request"]
|
||||
|
||||
- ID: "slackapi_service"
|
||||
Type: "slackapi"
|
||||
UserID: "@slackapi:{{ matrix_domain }}"
|
||||
Config:
|
||||
Hooks:
|
||||
"hook1":
|
||||
RoomID: "!someroom:id"
|
||||
MessageType: "m.text" # default is m.text
|
||||
|
||||
- ID: "alertmanager_service"
|
||||
Type: "alertmanager"
|
||||
UserID: "@alertmanager:{{ matrix_domain }}"
|
||||
Config:
|
||||
# This is for information purposes only. It should point to Go-NEB path as follows:
|
||||
# `/services/hooks/<base64 encoded service ID>`
|
||||
# Where in this case "service ID" is "alertmanager_service"
|
||||
# Make sure your BASE_URL can be accessed by the Alertmanager instance!
|
||||
webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
|
||||
# Each room will get the notification with the alert rendered with the given template
|
||||
rooms:
|
||||
"!someroomid:domain.tld":
|
||||
text_template: "{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}"
|
||||
html_template: "{{range .Alerts -}} {{ $severity := index .Labels \"severity\" }} {{ if eq .Status \"firing\" }} {{ if eq $severity \"critical\"}} <font color='red'><b>[FIRING - CRITICAL]</b></font> {{ else if eq $severity \"warning\"}} <font color='orange'><b>[FIRING - WARNING]</b></font> {{ else }} <b>[FIRING - {{ $severity }}]</b> {{ end }} {{ else }} <font color='green'><b>[RESOLVED]</b></font> {{ end }} {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}} <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}"
|
||||
msg_type: "m.text" # Must be either `m.text` or `m.notice`
|
||||
```
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
Don't forget to add `goneb.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
|
||||
|
||||
After configuring the playbook, run the [installation](installing.md) command again:
|
||||
|
||||
```
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:DOMAIN` where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
|
||||
|
||||
Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
|
||||
|
||||
If you enabled the github_cmd service you can get the supported commands via `!github help`
|
||||
|
||||
You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).
|
||||
@ -59,7 +59,7 @@ Name | Description
|
||||
`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`|Set this to a password to use for HTTP Basic Auth for protecting `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus` - it's not configurable)
|
||||
|
||||
|
||||
## More inforation
|
||||
## More information
|
||||
|
||||
- [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
|
||||
- [The Prometheus scraping rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus) (we use v2)
|
||||
|
||||
@ -8,15 +8,15 @@ To configure the playbook, you need to have done the following things:
|
||||
|
||||
You can then follow these steps inside the playbook directory:
|
||||
|
||||
- create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
|
||||
1. create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
|
||||
|
||||
- copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
|
||||
1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
|
||||
|
||||
- edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at the various `roles/ROLE_NAME_HERE/defaults/main.yml` files and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
|
||||
1. edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at the various `roles/ROLE_NAME_HERE/defaults/main.yml` files and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
|
||||
|
||||
- copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
|
||||
1. copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
|
||||
|
||||
- edit the inventory hosts file (`inventory/hosts`) to your liking
|
||||
1. edit the inventory hosts file (`inventory/hosts`) to your liking
|
||||
|
||||
|
||||
For a basic Matrix installation, that's all you need.
|
||||
@ -130,3 +130,5 @@ When you're done with all the configuration you'd like to do, continue with [Ins
|
||||
### Bots
|
||||
|
||||
- [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) (optional)
|
||||
|
||||
- [Setting up Go-NEB](configuring-playbook-bot-go-neb.md) (optional)
|
||||
|
||||
@ -88,6 +88,8 @@ These services are not part of our default installation, but can be enabled by [
|
||||
|
||||
- [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)
|
||||
|
||||
- [matrixdotorg/go-neb](https://hub.docker.com/r/matrixdotorg/go-neb) - the [Go-NEB](https://github.com/matrix-org/go-neb) bot (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)
|
||||
|
||||
- [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) - [Prometheus](https://github.com/prometheus/prometheus/) is a systems and service monitoring system
|
||||
|
||||
Reference in New Issue
Block a user