2021-03-11 18:23:01 +00:00
# Setting up Go-NEB (optional)
2024-10-28 07:34:20 +00:00
**Note**: [Go-NEB ](https://github.com/matrix-org/go-neb ) is now an archived (**unmaintained**) project. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot ](https://github.com/matrix-org/matrix-hookshot ) as a replacement, which can also be installed using [this playbook ](configuring-playbook-bridge-hookshot.md ). Consider using that bot instead of this one.
2024-10-26 12:42:59 +00:00
2021-03-11 18:23:01 +00:00
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.
2021-03-16 06:02:20 +00:00
## Registering the bot user
2021-03-11 18:23:01 +00:00
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` .
2021-03-16 06:02:20 +00:00
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
```
2022-08-20 09:47:14 +00:00
Once the user is created you can [obtain an access token ](obtaining-access-tokens.md ).
2021-03-11 18:23:01 +00:00
## Adjusting the playbook configuration
2024-10-20 20:07:51 +00:00
To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
2021-03-11 18:23:01 +00:00
```yaml
matrix_bot_go_neb_enabled: true
# You need at least 1 client.
2021-03-16 06:02:20 +00:00
# Use the access token you obtained in the step above.
2021-03-11 18:23:01 +00:00
matrix_bot_go_neb_clients:
2021-03-15 12:04:31 +00:00
- UserID: "@goneb:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
DeviceID: "DEVICE1"
2024-01-07 15:04:23 +00:00
HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
2021-03-11 18:23:01 +00:00
Sync: true
AutoJoinRooms: true
DisplayName: "Go-NEB!"
2021-03-15 12:04:31 +00:00
AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
2021-03-11 18:23:01 +00:00
2021-03-15 12:04:31 +00:00
- UserID: "@another_goneb:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
DeviceID: "DEVICE2"
2024-01-07 15:04:23 +00:00
HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
2021-03-11 18:23:01 +00:00
Sync: false
AutoJoinRooms: false
DisplayName: "Go-NEB!"
2021-03-15 12:04:31 +00:00
AcceptVerificationFromUsers: ["^@admin:{{ matrix_domain }}"]
2021-03-11 18:23:01 +00:00
# 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"
2021-03-15 12:04:31 +00:00
UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
2021-03-11 18:23:01 +00:00
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"
2021-03-15 12:04:31 +00:00
UserID: "@goneb:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
Config: {}
# Can be obtained from https://developers.giphy.com/dashboard/
- ID: "giphy_service"
Type: "giphy"
2021-03-15 12:04:31 +00:00
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
2021-03-11 18:23:01 +00:00
Config:
api_key: "qwg4672vsuyfsfe"
use_downsized: false
# This service has been dead for over a year :/
- ID: "guggy_service"
Type: "guggy"
2021-03-15 12:04:31 +00:00
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
2021-03-11 18:23:01 +00:00
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"
2021-03-15 12:04:31 +00:00
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
2021-03-11 18:23:01 +00:00
Config:
api_key: "AIzaSyA4FD39m9"
cx: "AIASDFWSRRtrtr"
# Get a key via https://api.imgur.com/oauth2/addclient
2021-03-15 12:04:31 +00:00
# Select "oauth2 without callback url"
2021-03-11 18:23:01 +00:00
- ID: "imgur_service"
Type: "imgur"
2021-03-15 12:04:31 +00:00
UserID: "@imgur:{{ matrix_domain }}" # requires a Syncing client
2021-03-11 18:23:01 +00:00
Config:
2021-03-15 12:04:31 +00:00
client_id: "AIzaSyA4FD39m9"
2021-03-15 12:08:59 +00:00
client_secret: "somesecret"
2021-03-11 18:23:01 +00:00
- ID: "wikipedia_service"
Type: "wikipedia"
2021-03-15 12:04:31 +00:00
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
2021-03-11 18:23:01 +00:00
Config:
- ID: "rss_service"
Type: "rssbot"
2021-03-15 12:04:31 +00:00
UserID: "@another_goneb:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
Config:
feeds:
"http://lorem-rss.herokuapp.com/feed?unit=second& interval=60":
2024-10-18 16:23:37 +00:00
rooms: ["!qporfwt:{{ matrix_domain }}"]
2021-03-11 18:23:01 +00:00
must_include:
author:
- author1
description:
- lorem
- ipsum
must_not_include:
title:
- Lorem
- Ipsum
- ID: "github_cmd_service"
Type: "github"
2021-03-15 12:04:31 +00:00
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
2021-03-11 18:23:01 +00:00
Config:
RealmID: "github_realm"
# Make sure your BASE_URL can be accessed by Github!
- ID: "github_webhook_service"
Type: "github-webhook"
2021-03-15 12:04:31 +00:00
UserID: "@another_goneb:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
Config:
RealmID: "github_realm"
2021-03-15 12:04:31 +00:00
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.
2021-03-11 18:23:01 +00:00
Rooms:
2024-10-18 16:23:37 +00:00
"!qporfwt:example.com":
2021-03-11 18:23:01 +00:00
Repos:
2024-01-17 05:58:01 +00:00
"element-hq/synapse":
2021-03-11 18:23:01 +00:00
Events: ["push", "issues"]
"matrix-org/dendron":
Events: ["pull_request"]
2024-10-18 16:20:08 +00:00
"!aaabaa:example.com":
2021-03-11 18:23:01 +00:00
Repos:
2024-01-17 05:58:01 +00:00
"element-hq/synapse":
2021-03-11 18:23:01 +00:00
Events: ["push", "issues"]
"matrix-org/dendron":
Events: ["pull_request"]
- ID: "slackapi_service"
Type: "slackapi"
2021-03-15 12:04:31 +00:00
UserID: "@slackapi:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
Config:
Hooks:
"hook1":
2024-10-18 16:23:37 +00:00
RoomID: "!qporfwt:example.com"
2021-03-11 18:23:01 +00:00
MessageType: "m.text" # default is m.text
- ID: "alertmanager_service"
Type: "alertmanager"
2021-03-15 12:04:31 +00:00
UserID: "@alertmanager:{{ matrix_domain }}"
2021-03-11 18:23:01 +00:00
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:
2024-10-18 16:23:37 +00:00
"!qporfwt:example.com":
2022-01-15 07:06:10 +00:00
text_template: "{% raw %}{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}{% endraw %}"
html_template: "{% raw %}{{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 -}}{% endraw %}"
2021-03-11 18:23:01 +00:00
msg_type: "m.text" # Must be either `m.text` or `m.notice`
```
2024-10-20 20:07:51 +00:00
### Adjusting the Go-NEB URL
By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to [adjust your DNS records ](#adjusting-dns-records ).
By tweaking the `matrix_bot_go_neb_hostname` and `matrix_bot_go_neb_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Go-NEB.
matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /buscarron subpath
matrix_bot_go_neb_path_prefix: /go-neb
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
By default, you will need to create a CNAME record for `goneb` . See [Configuring DNS ](configuring-dns.md ) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
2021-03-11 18:23:01 +00:00
## Installing
2024-10-20 20:42:21 +00:00
After configuring the playbook and potentially [adjusting your DNS records ](#adjusting-dns-records ), run the [installation ](installing.md ) command:
2021-03-11 18:23:01 +00:00
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
2024-10-17 13:23:06 +00:00
To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:example .com` where `example.com` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
2021-03-11 18:23:01 +00:00
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 ).