apps
/
opensaps
2
0
Fork 0
Code Issues 6 Pull Requests Packages Projects Releases Wiki Activity

Documentation update.

This commit is contained in:
Stanislav Nikitin 2019-03-06 05:31:00 +05:00
parent eaf6b05a37
commit 56b38b798b
No known key found for this signature in database
GPG Key ID: 106900B32F8192EE
2 changed files with 43 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -1,14 +1,10 @@
# OpenSAPS # OpenSAPS
OpenSAPS stands for "Open Slack APi Server". This is an open-source OpenSAPS stands for "Open Slack APi Server". This is an open-source implementation of Slack API server that can be used to integrate applications into each other using Slack API.
implementation of Slack API server that can be used to integrate
applications into each other using Slack API.
Initially this project was created for integrating Gitlab and Gitea Initially this project was created for integrating Gitlab and Gitea into Matrix, because there was no good incoming webhooks support. But it can be used for anything that provides Slack Webhooks support.
into Matrix, because there was no good incoming webhooks support.
But it can be used for anything that provides Slack Webhooks support.
Join #opensaps:pztrn.name Matrix room for help and chat! Join [#opensaps:pztrn.name](https://matrix.to/#/#opensaps:pztrn.name) Matrix room for help and chat!
# Installation # Installation
@ -17,16 +13,15 @@ go get -u -v -d gitlab.com/pztrn/opensaps
go install -v gitlab.com/pztrn/opensaps go install -v gitlab.com/pztrn/opensaps
``` ```
Or drop into [tags section](https://gitlab.com/pztrn/opensaps/tags) to grab a precompiled binary!
# Configuration # Configuration
Take a look at ``opensaps.example.yaml`` for configuration example. Take a look at ``opensaps.example.yaml`` for configuration example. Right now there is no documentation about configuration file, but it will appear in future.
Right now there is no documentation about configuration file, but it
will appear in future.
# Usage # Usage
The only parameter OpenSAPS binary accepts is a configuration file The only parameter OpenSAPS binary accepts is a configuration file path. Do it like:
path. Do it like:
``` ```
opensaps -config /path/to/opensaps.yaml opensaps -config /path/to/opensaps.yaml
@ -36,13 +31,9 @@ There is some documentation available - check out ``doc`` directory!
# About hooks and parsers # About hooks and parsers
While configuring a webhook in your application, please, set username While configuring a webhook in your application, please, set username exactly same as one of parsers in ``parsers`` directory! Otherwise parser "default" will be used, which will just concatenate text and attachments into one message!
exactly same as one of parsers in ``parsers`` directory! Otherwise parser
"default" will be used, which will just concatenate text and attachments
into one message!
Also note - that nickname will be ignored while sending message to Also note - that nickname will be ignored while sending message to pushers.
pushers.
---- ----

58
doc/configuration.md
View File

@ -1,42 +1,34 @@
# OpenSAPS configuration # OpenSAPS configuration
There is no hardcoded place for OpenSAPS configuration. You **should** There is no hardcoded place for OpenSAPS configuration. You **should** provide path to configuration file via ``-config`` parameter.
provide path to configuration file via ``-config`` parameter.
# Example configuration # Example configuration
Example can be viewed in opensaps.example.yaml, which is stored in root Example can be viewed in opensaps.example.yaml, which is stored in root directory of this repository.
directory of this repository.
# Configuration values. # Configuration values.
Here we will go thru configuration values available. Nesting shows Here we will go thru configuration values available. Nesting shows nesting level in configuration file.
nesting level in configuration file.
* ``slackhandler`` - namespace for configuring Slack API HTTP listener. * ``slackhandler`` - namespace for configuring Slack API HTTP listener.
* ``listener`` - namespace for configuring HTTP listener itself. * ``listener`` - namespace for configuring HTTP listener itself.
* ``address`` - IP address and port we will listen on. Defaulting * ``address`` - IP address and port we will listen on. Defaulting to ``127.0.0.1:39231``.
to ``127.0.0.1:39231``.
* ``webhooks`` - namespace for webhooks configuration. Here you should * ``webhooks`` - namespace for webhooks configuration. Here you should define webhook name (**should be unique!**) and some parameters.
define webhook name (**should be unique!**) and some parameters.
* ``gitea_to_matrix`` - example webhook name. Should be unique and * ``gitea_to_matrix`` - example webhook name. Should be unique and can be anything you can imagine (in text, of course).
can be anything you can imagine (in text, of course).
**WARNING:** multiline webhook names wasn't tested! Try to keep **WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line!
your text in single line!
* ``slack`` - namespace for configuring Slack API parameters. * ``slack`` - namespace for configuring Slack API parameters. URL for Slack webhook looks like:
URL for Slack webhook looks like:
``` ```
http(s)://server.tls/services/T12345678/B87654321/24charslongstring http(s)://server.tls/services/T12345678/B87654321/24charslongstring
``` ```
Where ``12345678`` is a random 8-char string (all caps) and Where ``12345678`` is a random 8-char string (all caps) and ``24charslongstring`` is a random 24-char string.
``24charslongstring`` is a random 24-char string.
Next variables configures these strings. Next variables configures these strings.
@ -55,11 +47,10 @@ define webhook name (**should be unique!**) and some parameters.
* ``matrix`` - configures Matrix pusher connections available. * ``matrix`` - configures Matrix pusher connections available.
* ``matrix_test`` - connection name. Should be unique and * ``matrix_test`` - connection name. Should be unique and can be anything you can imagine (in text, of course).
can be anything you can imagine (in text, of course).
**WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line!
**WARNING:** multiline webhook names wasn't tested! Try to keep
your text in single line!
* ``api_root`` - API root for Matrix connection. For example, * ``api_root`` - API root for Matrix connection. For example,
``https://localhost:8448/_matrix/client/r0``. ``https://localhost:8448/_matrix/client/r0``.
@ -67,5 +58,24 @@ define webhook name (**should be unique!**) and some parameters.
* ``password`` - password for Matrix user. * ``password`` - password for Matrix user.
* ``room`` - room ID to use. If Matrix user isn't in that room * ``room`` - room ID to use. If Matrix user isn't in that room while OpenSAPS logging in - OpenSAPS will try to join this room.
while OpenSAPS logging in - OpenSAPS will try to join this room.
* ``telegram`` - configures Telegram pusher connections.
* ``telegram_test`` - connection name. Should be unique and can be anything you can imagine (in text, of course).
* ``bot_id`` - token from BotFather.
* ``chat_id`` - chat ID to where OpenSAPS will write message. Easies way to get it - invite bot into chat (or start chat with bot), send a message and go to https://api.telegram.org/botYOUR:BOTTOKEN/getUpdates to obtain chat ID. It can be positive (for privates) and negative (for groupchats).
* ``proxy`` - proxy configuration for Telegram connection. This configuration is **connection-specific**.
* ``enabled`` - should we use proxy or not.
* ``type`` - proxy type. For now ignored as only HTTP proxy support is available.
* ``address`` - proxy server address in format "address:port".
* ``user`` - this username will be used for authorization if filled.
* ``password`` - this password will be used for authorization if filled **and** if username is also filled.