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

Some documentation fixes, related to #4.

This commit is contained in:
Stanislav Nikitin 2019-03-12 21:46:29 +05:00
parent 4e69625994
commit 25ab43c8ba
No known key found for this signature in database
GPG Key ID: 106900B32F8192EE
3 changed files with 39 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -6,7 +6,7 @@ Initially this project was created for integrating Gitlab and Gitea into Matrix,
Join [#opensaps:pztrn.name](https://matrix.to/#/#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
``` ```
go get -u -v -d gitlab.com/pztrn/opensaps go get -u -v -d gitlab.com/pztrn/opensaps
@ -15,28 +15,30 @@ go install -v gitlab.com/pztrn/opensaps
Or drop into [tags section](https://gitlab.com/pztrn/opensaps/tags) to grab a precompiled binary! 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. 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 and into [docs section](/doc/configuration.md) for configuration file fields description.
# Usage ## 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:
``` ```bash
opensaps -config /path/to/opensaps.yaml opensaps -config /path/to/opensaps.yaml
``` ```
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 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. Nickname under which messages will appear depends on your account's configuration.
## Known to work good software
[There is a list of software](/doc/software_that_works_good.md) that known to work fine with OpenSAPS. Check it out!
---- ----
# IMPORTANT NOTICE ## IMPORTANT NOTICE
This project isn't affiliated nor developed by Slack itself. This project isn't affiliated nor developed by Slack itself.

34
doc/configuration.md
View File

@ -2,11 +2,11 @@
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 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. ## 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.
@ -20,12 +20,12 @@ Here we will go thru configuration values available. Nesting shows nesting level
* ``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! **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: * ``slack`` - namespace for configuring Slack API parameters. URL for Slack webhook looks like:
``` ```text
http(s)://server.tls/services/T12345678/B87654321/24charslongstring http(s)://server.tls/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.
@ -41,15 +41,15 @@ Here we will go thru configuration values available. Nesting shows nesting level
* ``remote`` - configures pusher this webhook should use and * ``remote`` - configures pusher this webhook should use and
connection name for it. connection name for it.
* ``pusher`` - what pusher this webhook should use. * ``pusher`` - what pusher (protocol) this webhook should use to retransmit received data.
* ``push_to`` - connection name for this pusher. * ``push_to`` - connection name for this pusher. It should be defined below for pusher defined above.
* ``matrix`` - configures Matrix pusher connections available. * ``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, * ``api_root`` - API root for Matrix connection. For example,
``https://localhost:8448/_matrix/client/r0``. ``https://localhost:8448/_matrix/client/r0``.
@ -63,19 +63,19 @@ Here we will go thru configuration values available. Nesting shows nesting level
* ``telegram`` - configures Telegram pusher connections. * ``telegram`` - configures Telegram pusher connections.
* ``telegram_test`` - connection name. Should be unique and can be anything you can imagine (in text, of course). * ``telegram_test`` - connection name. Should be unique and can be anything you can imagine (in text, of course).
* ``bot_id`` - token from BotFather. * ``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). * ``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**. * ``proxy`` - proxy configuration for Telegram connection. This configuration is **connection-specific**.
* ``enabled`` - should we use proxy or not. * ``enabled`` - should we use proxy or not.
* ``type`` - proxy type. For now ignored as only HTTP proxy support is available. * ``type`` - proxy type. For now ignored as only HTTP proxy support is available.
* ``address`` - proxy server address in format "address:port". * ``address`` - proxy server address in format "address:port".
* ``user`` - this username will be used for authorization if filled. * ``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. * ``password`` - this password will be used for authorization if filled **and** if username is also filled.

10
doc/software_that_works_good.md Normal file
View File

@ -0,0 +1,10 @@
# Software that works good
Here goes a list of software that works good with OpenSAPS.
If there is a need of additional configuration and/or patches - it will be mentioned.
Create PR if you want to add software here.
* [Gitea](https://gitea.io) - works fine with default parser.
* [Gitlab](https://gitlab.com) both gitlab.com and self-hosted - works fine with default parser.