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 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.
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.
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.
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.
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
@ -17,16 +13,15 @@ go get -u -v -d 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
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.
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.
# Usage
The only parameter OpenSAPS binary accepts is a configuration file
path. Do it like:
The only parameter OpenSAPS binary accepts is a configuration file path. Do it like:
```
opensaps -config /path/to/opensaps.yaml
@ -36,13 +31,9 @@ There is some documentation available - check out ``doc`` directory!
# About hooks and parsers
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!
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!
Also note - that nickname will be ignored while sending message to
pushers.
Also note - that nickname will be ignored while sending message to pushers.
----

58
doc/configuration.md
View File

@ -1,42 +1,34 @@
# OpenSAPS configuration
There is no hardcoded place for OpenSAPS configuration. You **should**
provide path to configuration file via ``-config`` parameter.
There is no hardcoded place for OpenSAPS configuration. You **should** provide path to configuration file via ``-config`` parameter.
# Example configuration
Example can be viewed in opensaps.example.yaml, which is stored in root
directory of this repository.
Example can be viewed in opensaps.example.yaml, which is stored in root directory of this repository.
# Configuration values.
Here we will go thru configuration values available. Nesting shows
nesting level in configuration file.
Here we will go thru configuration values available. Nesting shows nesting level in configuration file.
* ``slackhandler`` - namespace for configuring Slack API HTTP listener.
* ``listener`` - namespace for configuring HTTP listener itself.
* ``address`` - IP address and port we will listen on. Defaulting
to ``127.0.0.1:39231``.
* ``address`` - IP address and port we will listen on. Defaulting to ``127.0.0.1:39231``.
* ``webhooks`` - namespace for webhooks configuration. Here you should
define webhook name (**should be unique!**) and some parameters.
* ``webhooks`` - namespace for webhooks configuration. Here you should define webhook name (**should be unique!**) and some parameters.
* ``gitea_to_matrix`` - example webhook name. Should be unique and
can be anything you can imagine (in text, of course).
* ``gitea_to_matrix`` - example webhook name. Should be unique and 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!
* ``slack`` - namespace for configuring Slack API parameters.
URL for Slack webhook looks like:
**WARNING:** multiline webhook names wasn't tested! Try to keep your text in single line!
* ``slack`` - namespace for configuring Slack API parameters. URL for Slack webhook looks like:
```
http(s)://server.tls/services/T12345678/B87654321/24charslongstring
```
Where ``12345678`` is a random 8-char string (all caps) and
``24charslongstring`` is a random 24-char string.
Where ``12345678`` is a random 8-char string (all caps) and ``24charslongstring`` is a random 24-char string.
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_test`` - connection name. Should be unique and
can be anything you can imagine (in text, of course).
* ``matrix_test`` - connection name. Should be unique and 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,
``https://localhost:8448/_matrix/client/r0``.
@ -67,5 +58,24 @@ define webhook name (**should be unique!**) and some parameters.
* ``password`` - password for Matrix user.
* ``room`` - room ID to use. If Matrix user isn't in that room
while OpenSAPS logging in - OpenSAPS will try to join this 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.
* ``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.