README.md 3.54 KB
Newer Older
Krille Fear's avatar
Krille Fear committed
1
# Matrix Hedwig
Niklas Zender's avatar
Niklas Zender committed
2
3
4
5
6
7
8
9
10
11

[![pipeline status][badge-pipeline-img]][badge-pipeline-url]
[![coverage report][badge-coverage-img]][badge-coverage-url]

[badge-coverage-img]: https://gitlab.com/famedly/company/backend/services/hedwig/badges/main/coverage.svg
[badge-coverage-url]: https://gitlab.com/famedly/company/backend/services/hedwig/-/commits/main
[badge-pipeline-img]: https://gitlab.com/famedly/company/backend/services/hedwig/badges/main/pipeline.svg
[badge-pipeline-url]: https://gitlab.com/famedly/company/backend/services/hedwig/-/commits/main


Krille Fear's avatar
Krille Fear committed
12
This is a dead simple Push Gateway for a [Matrix.org](https://matrix.org) application. It implements the [Matrix Push Notification API r0.1.1](https://matrix.org/docs/spec/push_gateway/r0.1.1) and supports [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) only.
Krille Fear's avatar
Krille Fear committed
13

Krille Fear's avatar
Krille Fear committed
14
15
16
17
## Features:
- Implements the `POST /_matrix/push/v1/notify` endpoint
- Forwards notifications from the format `event_id_only`
- Returns invalid push keys in the `rejected` response field
Krille Fear's avatar
Krille Fear committed
18
19
20
- Health status endpoint at `GET /health`
- Version endpoint at `GET /version`
- Prometheus metrics at `GET /metrics`
Krille Fear's avatar
Krille Fear committed
21
22
23
24
25

## Planned:
- Better logging

# Get started
Krille Fear's avatar
Krille Fear committed
26
1. Download the latest build from the CI: [amd64](https://gitlab.com/famedly/services/famedly-push-gateway-ng/-/jobs/artifacts/main/browse?job=cargo-build-amd64), [armv7](https://gitlab.com/famedly/services/famedly-push-gateway-ng/-/jobs/artifacts/main/browse?job=cargo-build-armv7), [aarch64](https://gitlab.com/famedly/services/famedly-push-gateway-ng/-/jobs/artifacts/main/browse?job=cargo-build-aarch64)
Krille Fear's avatar
Krille Fear committed
27

28
2. Add your Firebase Admin Key to the `config.yaml` file
Krille Fear's avatar
Krille Fear committed
29
30

3. Run the binary
31
32
33
34
```
./matrix-hedwig
```

Krille Fear's avatar
Krille Fear committed
35
36
37
38
## Data Messages and Notification Messages

In FCM there are two kind of messages: Data Messages and Notification Messages. Read more about it here: https://firebase.google.com/docs/cloud-messaging/concept-options

39
By default Hedwig is sending Notification Messages which payload you can configure in the `config.yaml`. To send Data Messages, just append `.data_message` to the APP ID.
Krille Fear's avatar
Krille Fear committed
40

41
42
43
44
45
46
47
## Proxy

You should configure a proxy with a working SSL connection to the gateway.

### Apache2 example

```
Krille Fear's avatar
Krille Fear committed
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
<Location "/_matrix/push/v1/">
  ProxyPass "http://localhost:7025/_matrix/push/v1/"
  SetEnv force-proxy-request-1.0 1
  SetEnv proxy-nokeepalive 1
</Location>
```

And optional:

```
<Location "/_matrix/push/health">
  ProxyPass "http://localhost:7025/health"
  SetEnv force-proxy-request-1.0 1
  SetEnv proxy-nokeepalive 1
</Location>

<Location "/_matrix/push/version">
  ProxyPass "http://localhost:7025/version"
66
67
68
69
  SetEnv force-proxy-request-1.0 1
  SetEnv proxy-nokeepalive 1
</Location>
```
Krille Fear's avatar
Krille Fear committed
70

71
72
73
## Docker

We provide a docker image with the compiled binary inside it. To use it, you need to map your
74
`config.yaml` into `/opt/hedwig/config.yaml` inside the container, and then you can route your
75
76
77
78
79
80
81
82
83
84
85
traffic to the configured listening port (default is `7022`).

Example usage with docker cli:

```
docker run --rm --name hedwig \
    -v ./config.toml:/opt/hedwig/config.toml \
    -p 127.0.0.1:7022:7022 \
    registry.gitlab.com/famedly/services/hedwig:latest
```

Krille Fear's avatar
Krille Fear committed
86
87
88
89
90
91
92
93
# How to build for your platform

1. [Install Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)

2. Build the binary:
```
cargo build --release
```
Felix Dommes's avatar
Felix Dommes committed
94
95
96
97
98
99

# Pre-commit usage

1. If not installed, install with your package manager, or `pip install --user pre-commit`
2. Run `pre-commit autoupdate` to update the pre-commit config to use the newest template
3. Run `pre-commit install` to install the pre-commit hooks to your local environment