mirror of
https://github.com/pushbits/server.git
synced 2025-06-04 03:32:24 +02:00
202 lines
8.6 KiB
Markdown
202 lines
8.6 KiB
Markdown
| :exclamation: **This software is currently in alpha phase.** |
|
|
|-----------------------------------------------------------------|
|
|
|
|
<div align="center">
|
|
<h1>PushBits</h1>
|
|
<h4 align="center">
|
|
Receive your important notifications immediately, over <a href="https://matrix.org/">Matrix</a>.
|
|
</h4>
|
|
<p>PushBits enables you to send push notifications via a simple web API, and delivers them to your users.</p>
|
|
</div>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/pushbits/server/actions"><img alt="Build status" src="https://img.shields.io/github/workflow/status/pushbits/server/Main"/></a>
|
|
<a href="https://github.com/pushbits/server/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/pushbits/server"/></a>
|
|
</p>
|
|
|
|
## 💡 About
|
|
|
|
PushBits is a relay server for push notifications.
|
|
It enables you to send notifications via a simple web API, and delivers them to you through [Matrix](https://matrix.org/).
|
|
This is similar to what [Pushover](https://pushover.net/) and [Gotify](https://gotify.net/) offer, but it does not require an additional app.
|
|
|
|
The vision is to have compatibility with Gotify on the sending side, while on the receiving side an established service is used.
|
|
This has the advantages that
|
|
- sending plugins written for Gotify (like those for [Watchtower](https://containrrr.dev/watchtower/) and [Jellyfin](https://jellyfin.org/)) as well as
|
|
- receiving clients written for Matrix
|
|
can be reused.
|
|
|
|
### Why Matrix instead of X?
|
|
|
|
This project totally would've used Signal if it would offer a proper API.
|
|
Sadly, neither [Signal](https://signal.org/) nor [WhatsApp](https://www.whatsapp.com/) come with an API (at the time of writing) through which PushBits could interact.
|
|
|
|
In [Telegram](https://telegram.org/) there is an API to run bots, but these are limited in that they cannot create chats by themselves.
|
|
If you insist on going with Telegram, have a look at [webhook2telegram](https://github.com/muety/webhook2telegram).
|
|
|
|
The idea of a federated, synchronized but yet end-to-end encrypted protocol is awesome, but its clients simply aren't really there yet.
|
|
Still, if you haven't tried it yet, we'd encourage you to check it out.
|
|
|
|
## 🤘 Features
|
|
|
|
- [x] Multiple users and multiple channels (applications) per user
|
|
- [x] Compatibility with Gotify's API for sending messages
|
|
- [x] API and CLI for managing users and applications
|
|
- [x] Optional check for weak passwords using [HIBP](https://haveibeenpwned.com/)
|
|
- [x] Argon2 as KDF for password storage
|
|
- [ ] Two-factor authentication, [issue](https://github.com/pushbits/server/issues/19)
|
|
- [ ] Bi-directional key verification, [issue](https://github.com/pushbits/server/issues/20)
|
|
|
|
## 🚀 Installation
|
|
|
|
PushBits is meant to be self-hosted.
|
|
That means you have to install it on your own server.
|
|
|
|
Currently, the only supported way of installing PushBits is via [Docker](https://www.docker.com/) or [Podman](https://podman.io/).
|
|
The image is hosted [via ghcr.io](https://github.com/pushbits/server/pkgs/container/server).
|
|
|
|
| :warning: **You are advised to install PushBits behind a reverse proxy and enable TLS.** Otherwise, your credentials will be transmitted unencrypted. |
|
|
|----------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
|
|
## ⚙ Configuration
|
|
|
|
To see what can be configured, have a look at the `config.sample.yml` file inside the root of the repository.
|
|
|
|
Settings can optionally be provided via environment variables.
|
|
The name of the environment variable is composed of a starting `PUSHBITS_`, followed by the keys of the setting, all
|
|
joined with `_`.
|
|
As an example, the HTTP port can be provided as an environment variable called `PUSHBITS_HTTP_PORT`.
|
|
|
|
To get started, here is a Docker Compose file you can use.
|
|
```yaml
|
|
version: '2'
|
|
|
|
services:
|
|
server:
|
|
image: ghcr.io/pushbits/server:latest
|
|
ports:
|
|
- 8080:8080
|
|
environment:
|
|
PUSHBITS_DATABASE_DIALECT: 'sqlite3'
|
|
PUSHBITS_ADMIN_MATRIXID: '@your/matrix/username:matrix.org' # The Matrix account on which the admin will receive their notifications.
|
|
PUSHBITS_ADMIN_PASSWORD: 'your/pushbits/password' # The login password of the admin account. Default username is 'admin'.
|
|
PUSHBITS_MATRIX_USERNAME: 'your/matrix/username' # The Matrix account from which notifications are sent to all users.
|
|
PUSHBITS_MATRIX_PASSWORD: 'your/matrix/password' # The password of the above account.
|
|
volumes:
|
|
- /etc/localtime:/etc/localtime:ro
|
|
- /etc/timezone:/etc/timezone:ro
|
|
- ./data:/data
|
|
```
|
|
|
|
In this example, the configuration file would be located at `./data/config.yml` on the host.
|
|
The SQLite database would be written to `./data/pushbits.db`.
|
|
**Don't forget to adjust the permissions** of the `./data` directory, otherwise PushBits will fail to operate.
|
|
|
|
## 📄 Usage
|
|
|
|
Now, how can you interact with the server?
|
|
We provide [a little CLI tool called pbcli](https://github.com/PushBits/cli) to make basic API requests to the server.
|
|
It helps you to create new users and applications.
|
|
You will find further instructions in the linked repository.
|
|
|
|
At the time of writing, there is no fancy GUI built-in, and we're not sure if this is necessary at all.
|
|
Currently, we would like to avoid front end development, so if you want to contribute in this regard we're happy if you reach out!
|
|
|
|
After you have created a user and an application, you can use the API to send a push notification to your Matrix account.
|
|
|
|
```bash
|
|
curl \
|
|
--header "Content-Type: application/json" \
|
|
--request POST \
|
|
--data '{"message":"my message","title":"my title"}' \
|
|
"https://pushbits.example.com/message?token=$PB_TOKEN"
|
|
```
|
|
|
|
Note that the token is associated with your application and has to be kept secret.
|
|
You can retrieve the token using [pbcli](https://github.com/PushBits/cli) by running following command.
|
|
|
|
```bash
|
|
pbcli application show $PB_APPLICATION --url https://pushbits.example.com --username $PB_USERNAME
|
|
```
|
|
|
|
### Message options
|
|
|
|
Messages can be specified in three different syntaxes:
|
|
|
|
* `text/plain`
|
|
* `text/html`
|
|
* `text/markdown`
|
|
|
|
To set a specific syntax you need to set the `extras` parameter ([inspired by Gotify's message extras](https://gotify.net/docs/msgextras#clientdisplay)):
|
|
|
|
```bash
|
|
curl \
|
|
--header "Content-Type: application/json" \
|
|
--request POST \
|
|
--data '{"message":"my message with\n\n**Markdown** _support_.","title":"my title","extras":{"client::display":{"contentType": "text/markdown"}}}' \
|
|
"https://pushbits.example.com/message?token=$PB_TOKEN"
|
|
```
|
|
|
|
HTML content might not be fully rendered in your Matrix client; see the corresponding [Matrix specs](https://spec.matrix.org/unstable/client-server-api/#mroommessage-msgtypes).
|
|
This also holds for Markdown, as it is translated into the corresponding HTML syntax.
|
|
|
|
### Deleting a Message
|
|
|
|
You can delete a message, this will send a notification in response to the original message informing you that the message is "deleted".
|
|
|
|
To delete a message, you need its message ID which is provided as part of the response when you send the message.
|
|
The ID might contain characters not valid in URIs.
|
|
We hence provide an additional `id_url_encoded` field for messages; you can directly use it when deleting a message without performing encoding yourself.
|
|
|
|
```bash
|
|
curl \
|
|
--request DELETE \
|
|
"https://pushbits.example.com/message/${MESSAGE_ID}?token=$PB_TOKEN"
|
|
```
|
|
|
|
## 👮 Acknowledgments
|
|
|
|
The idea for this software and most parts of the initial source are heavily inspired by [Gotify](https://gotify.net/).
|
|
Many thanks to [jmattheis](https://jmattheis.de/) for his well-structured code.
|
|
|
|
## 💻 Development
|
|
|
|
The source code is located on [GitHub](https://github.com/pushbits/server).
|
|
You can retrieve it by checking out the repository as follows.
|
|
|
|
```bash
|
|
git clone https://github.com/pushbits/server.git
|
|
```
|
|
|
|
[](https://starchart.cc/pushbits/server)
|
|
|
|
### Testing
|
|
|
|
Testing is essential for delivering good and reliable software.
|
|
PushBits uses Go's integrated test features.
|
|
Unfortunately, writing tests is quite time consuming and therefore not every feature and every line of code is automatically tested.
|
|
Feel free to help us improve our tests.
|
|
|
|
To run tests for a single (sub)module you can simply execute the following command in the module's folder.
|
|
|
|
```bash
|
|
go test
|
|
```
|
|
|
|
To get the testing coverage for a module use the `-cover` flag.
|
|
|
|
```bash
|
|
go test -cover
|
|
```
|
|
|
|
To execute a single test use the `-run` flag.
|
|
|
|
```bash
|
|
go test -run "TestApi_getUser"
|
|
```
|
|
|
|
Running tests for all PushBits module is done like this:
|
|
|
|
```bash
|
|
make test
|
|
```
|