Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jc21/juxtapose
Juxtapose is a self-hosted web app to send notifications from incoming services
https://github.com/jc21/juxtapose
Last synced: 9 days ago
JSON representation
Juxtapose is a self-hosted web app to send notifications from incoming services
- Host: GitHub
- URL: https://github.com/jc21/juxtapose
- Owner: jc21
- License: mit
- Created: 2017-11-13T04:29:47.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-27T05:14:00.000Z (almost 2 years ago)
- Last Synced: 2024-08-01T13:34:26.518Z (3 months ago)
- Language: JavaScript
- Size: 4 MB
- Stars: 27
- Watchers: 4
- Forks: 3
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Juxtapose
> **[juhk-stuh-pohz, juhk-stuh-pohz]**
>
> *to place close together or side by side, especially for comparison or contrast*
This Web App is a self-hosted Web Service glue for some of the applications I use on a daily
basis. It's purpose is to notify you of events that you want to know about, without being
swamped in noise, thus improving productivity.
## Supported Services
**Incoming services via Webhooks:**
- Jira
- Bitbucket
- Docker Hub
- Gerrit
- Zendesk
- Jenkins - [requires plugin](https://github.com/jc21/juxtapose-jenkins-plugin/releases)
**Outgoing services**
- Slack (via Slack Bot)
- Jabber / XMPP
- Google Chat
- Pushover
## Features
- Easy to use interface to configure your services, templates and rules
- Configure multiple templates for each notification type
- Multiple users who can create and manage their own rules
- Per-rule filtering options based on incoming service
## Getting started
There are a few ways to run this app and most of the time you'll want to create a config file.
See `config/default.json` for an example of the config file. At this time only a Mysql/Mariadb database is supported.
When first run, the app will generate private and public gpg keys for use with JsonWebTokens. For security reasons these will not be saved
in the database and are instead saved in a config file in the `/config` directory.
### Method 1: Pre-built Docker Image with docker-compose and local mariadb
By far the easiest way to get up and running. Create this `docker-compose.yml`
```bash
version: "2"
services:
app:
image: jc21/juxtapose
ports:
- 80:80
environment:
- NODE_ENV=production
volumes:
- ./default.json:/app/config/default.json
depends_on:
- db
links:
- db
restart: on-failure
db:
image: mariadb
environment:
MYSQL_ROOT_PASSWORD: "juxtapose"
MYSQL_DATABASE: "juxtapose"
MYSQL_USER: "juxtapose"
MYSQL_PASSWORD: "juxtapose"
volumes:
- ./mysql:/var/lib/mysql
restart: on-failure
```
In this docker-compose file, your Juxtapose config file should be named `default.json` and should exist in the same directory as `docker-compose.yml`
This will define a Juxtapose container and also a Mariadb container to connect to. Make sure the database credentials match your config file entries.
Now it's time to start up the containers. First we'll start with the database first, because it takes a few seconds to intialize and in this time, the Juxtapose
app will crash if it can't connect to it. Hence we will initialize it on it's own first:
```bash
docker-compose up db
```
Check the output and make sure there were no errors.
Now start the app/whole stack:
```bash
docker-compose up
```
And observe the output.
### Method 2: Pre-built Docker Image with docker-compose and your own database
Create this `docker-compose.yml`
```bash
version: "2"
services:
app:
image: jc21/juxtapose
ports:
- 80:80
environment:
- NODE_ENV=production
volumes:
- ./default.json:/app/config/default.json
restart: on-failure
```
In this docker-compose file, your Juxtapose config file should be named `default.json` and should exist in the same directory as `docker-compose.yml`
Make sure your config database settings are correct! Juxtapose only needs a new, empty database to get started.
Now start the app:
```bash
docker-compose up
```
And observe the output.
### Method 3: Pre-built Docker Image with your own database
Run this:
```bash
docker run --name juxtapose -p 80:80 -e NODE_ENV=production -v "./default.json:/app/config/default.json" jc21/juxtapose
```
For this example, your Juxtapose config file should be named `default.json` and should exist in the current directory.
Make sure your config database settings are correct! Juxtapose only needs a new, empty database to get started.
## Default User
Juxtapose will create an admin user when it initialises the database. The login details are:
- Email: `[email protected]`
- Password: `changeme`
## Known issues
### Slack Login Failures
When the credentials for a Slack bot are invalid it crashes the entire app. This is due mainly
to the `slackbots` package throwing errors incorrectly imo. Make sure you specify the correct
credentials when creating a Slack bot service. If you encounter this issue, simply remove the service
from the database with:
```sql
DELETE FROM `service` WHERE `type` = "slack";
-- alternatively update the api token:
UPDATE `service` SET `data` = '{"api_token":"NEWTOKEN"}' WHERE `type` = "slack";
```
## Advanced Topics
### LDAP Authentication setup
Add the following configuration to the config file in order to use LDAP:
```json
"ldap": {
"server": "ldap.example.com",
"userSearchBase": "cn=users,dc=com",
"usernameAttribute": "uid"
}
```
### Template Language Tips
This project uses [Liquid template engine](http://shopify.github.io/liquid/basics/introduction/) for dynamic notification content.
This means that your Templates can contain wildcards from the data supplied and also display different message content based on fields using control sturctues.
In addition to the functionality provided in the base Liquid engine, this project supports the following modifiers:
1. `unescape` - Will convert HTML entities like `&` to `&`.
Example: `{{ summary | unescape }}`
2. `jsonstring` - Will take any data type and return it as a JSON encoded string. Be aware that the string will be prepended/appended with the `"` double quotes.
Example: `{{ issuetype | jsonstring }}`
3. `jsonescape` - Will make a data type compatible to be included in a existing json string. It will also `unescape` for you. Does not prepend/append `"` double quotes.
Example: `{{ summary | jsonescape }}`
### Proxy
Should you be running behind a HTTP Proxy, just specify the `HTTP_PROXY` environment variable. Note: Proxy support was added in v1.0.1
Google Hangouts Chat does not work behind a proxy, due to Google NodeJS Libraries lack of support.
```bash
version: "2"
services:
app:
image: jc21/juxtapose
ports:
- 80:80
environment:
- NODE_ENV=production
- HTTP_PROXY=http://10.60.10.1:3128
volumes:
- ./default.json:/app/config/default.json
depends_on:
- db
links:
- db
restart: on-failure
db:
image: mariadb
environment:
MYSQL_ROOT_PASSWORD: "juxtapose"
MYSQL_DATABASE: "juxtapose"
MYSQL_USER: "juxtapose"
MYSQL_PASSWORD: "juxtapose"
volumes:
- ./mysql:/var/lib/mysql
restart: on-failure
```
or
```bash
docker run --name juxtapose -p 80:80 -e NODE_ENV=production -e HTTP_PROXY=http://10.60.10.1:3128 -v "./default.json:/app/config/default.json" jc21/juxtapose
```
## Screenshots
[](https://public.jc21.com/juxtapose/screenshots/login.jpg)
[](https://public.jc21.com/juxtapose/screenshots/rules.jpg)
[](https://public.jc21.com/juxtapose/screenshots/edit_template.jpg)
[](https://public.jc21.com/juxtapose/screenshots/new_rule_template_bitbucket.jpg)
[](https://public.jc21.com/juxtapose/screenshots/new_rule_template_jira.jpg)
[](https://public.jc21.com/juxtapose/screenshots/new_rule_trigger_bitbucket.jpg)
[](https://public.jc21.com/juxtapose/screenshots/new_rule_trigger_jira.jpg)
[](https://public.jc21.com/juxtapose/screenshots/services.jpg)
## Slack Bot Permissions
In order for this app to work with your Slack bot, it will require the following `OAuth & Permissions` Scopes:
**Bot Token Scopes**
- `channels:read`
- `chat:write`
- `chat:write.customize`
- `users:read`
- `users:read.email`