3pp-mirror/pushbits
1
0
Fork 0
mirror of https://github.com/pushbits/server.git synced 2025-04-28 17:56:50 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add link to new documentation

Browse source
This commit is contained in:
eikendev 2021-11-06 15:31:30 +01:00
parent 34d35219e0
commit 333fabea60
No known key found for this signature in database
GPG key ID: A1BDB1B28C8EF694
2 changed files with 5 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

142
README.md
View file

@ -10,8 +10,10 @@
</div>
<p align="center">
<a href="https://www.pushbits.io/docs/"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-success"/></a>&nbsp;
<a href="https://www.pushbits.io/api/"><img alt="API Documentation" src="https://img.shields.io/badge/api docs-online-success"/></a>&nbsp;
<a href="https://github.com/pushbits/server/actions"><img alt="Build status" src="https://img.shields.io/github/workflow/status/pushbits/server/Main"/></a>&nbsp;
<a href="https://github.com/pushbits/server/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/pushbits/server"/></a>&nbsp;
<a href="https://github.com/pushbits/server/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/pushbits/server"/></a>
</p>
## 💡&nbsp;About
@ -47,113 +49,6 @@ Still, if you haven't tried it yet, we'd encourage you to check it out.
- [ ] Two-factor authentication, [issue](https://github.com/pushbits/server/issues/19)
- [ ] Bi-directional key verification, [issue](https://github.com/pushbits/server/issues/20)
## 🚀&nbsp;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. |
|----------------------------------------------------------------------------------------------------------------------------------------------------------|
## ⚙&nbsp;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.
## 📄&nbsp;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"
```
## 👮&nbsp;Acknowledgments
The idea for this software and most parts of the initial source are heavily inspired by [Gotify](https://gotify.net/).
@ -169,34 +64,3 @@ git clone https://github.com/pushbits/server.git
```
[![Stargazers over time](https://starchart.cc/pushbits/server.svg)](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
```

4
cmd/pushbits/main.go
View file

@ -28,10 +28,10 @@ func setupCleanup(db *database.Database, dp *dispatcher.Dispatcher) {
// @title PushBits Server API Documentation
// @version 0.7.2
// @description Documentation for the PushBits server API. <br> [Contact](https://www.eiken.dev/)
// @description Documentation for the PushBits server API.
// @contact.name PushBits
// @contact.url https://github.com/pushbits
// @contact.url https://www.pushbits.io
// @license.name ISC
// @license.url https://github.com/pushbits/server/blob/master/LICENSE