Deploying PushBits

Introduction

PushBits is a self-hosted notification relay server that receives push notifications via a simple REST API and forwards them to Matrix rooms. It provides a privacy-respecting alternative to proprietary push notification services like Pushover or Pushbullet.

Built with Go, PushBits is lightweight, fast, and easy to deploy. It uses Matrix as the delivery backend, allowing you to receive notifications on any Matrix client across all your devices without relying on third-party services.

Key highlights of PushBits:

• Self-Hosted: Complete control over your notification infrastructure
• Matrix Integration: Leverages the Matrix network for delivery
• Simple API: Easy REST API for sending notifications
• Multi-User: Support for multiple users and applications
• Priority Levels: Different notification priorities
• Application Tokens: Secure per-application authentication
• Markdown Support: Rich text formatting in notifications
• Cross-Platform: Receive on any Matrix client
• Privacy Focused: No third-party data collection
• Open Source: Licensed under ISC

This guide walks through deploying PushBits on Klutch.sh using Docker.

Why Deploy PushBits on Klutch.sh

Deploying PushBits on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds PushBits without complex configuration.

Persistent Storage: Attach persistent volumes for database and configuration.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access.

GitHub Integration: Connect your repository directly from GitHub for automatic deployments.

Custom Domains: Assign a custom domain for your notification server.

Always-On Availability: Your notification server remains operational 24/7.

Prerequisites

Before deploying PushBits on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your PushBits configuration
• A Matrix account for the notification bot
• A Matrix room where notifications will be sent
• Basic familiarity with Docker and Matrix concepts
• (Optional) A custom domain for your PushBits instance

Understanding PushBits Architecture

PushBits works as a bridge between your applications and Matrix:

REST API: Receives notification requests from applications.

Matrix Bot: Authenticated Matrix user that sends messages to rooms.

Database: Stores users, applications, and configuration.

Application Tokens: Secure tokens for authenticating notification sources.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and PushBits configuration.

Repository Structure

pushbits-deploy/
├── Dockerfile
├── config.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/pushbits/server:latest

# Copy configuration
COPY config.yml /etc/pushbits/config.yml

# Create data directory
RUN mkdir -p /data

EXPOSE 8080

CMD ["pushbits", "serve", "--config", "/etc/pushbits/config.yml"]

Creating config.yml Configuration

Create a config.yml file with your PushBits configuration:

# PushBits Configuration

# HTTP settings
http:
  listenaddress: "0.0.0.0:8080"

# Database configuration
database:
  dialect: "sqlite"
  connection: "/data/pushbits.db"

# Matrix configuration
matrix:
  homeserver: "https://matrix.org"
  username: "@pushbits-bot:matrix.org"
  password: "${MATRIX_PASSWORD}"

# Admin configuration
admin:
  name: "admin"
  password: "${ADMIN_PASSWORD}"
  matrixid: "@your-matrix-id:matrix.org"

# Security settings
security:
  # Check application tokens strictly
  checktoken: true

# Formatting
formatting:
  # Use colored message formatting
  coloredtitle: true

# Logging
logging:
  level: "info"

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Deploying PushBits on Klutch.sh

Create a Matrix Bot Account

Create a Matrix account for PushBits to use:

1. Register a new account on your Matrix homeserver
2. Note the full Matrix ID (e.g., @pushbits:matrix.org)
3. Save the password securely

Create a Matrix Room

Create a room for notifications:

1. Create a new Matrix room
2. Invite the bot account
3. Note the room ID (e.g., !abc123:matrix.org)

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yml .dockerignore
git commit -m "Initial PushBits deployment configuration"
git remote add origin https://github.com/yourusername/pushbits-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “pushbits” or “notifications”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your PushBits Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

Add the following environment variables:

Variable	Value
MATRIX_PASSWORD	Your Matrix bot password
ADMIN_PASSWORD	Admin account password

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/data	1 GB	SQLite database
/etc/pushbits	100 MB	Configuration files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the PushBits container
• Provision an HTTPS certificate

Access PushBits

Once deployment completes, access your PushBits instance at https://your-app-name.klutch.sh. Log in with your admin credentials.

Creating Applications

Adding an Application

1. Log in to PushBits web interface
2. Click “Create Application”
3. Enter application name
4. Set the Matrix room ID for notifications
5. Save and copy the application token

Application Tokens

Each application gets a unique token:

• Keep tokens secure and private
• Tokens authenticate API requests
• Regenerate if compromised

Sending Notifications

Basic Notification

curl -X POST https://your-pushbits.klutch.sh/message \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-app-token",
    "title": "Alert",
    "message": "Something happened!"
  }'

With Priority

curl -X POST https://your-pushbits.klutch.sh/message \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-app-token",
    "title": "Critical Alert",
    "message": "Server is down!",
    "priority": 2
  }'

With Markdown

curl -X POST https://your-pushbits.klutch.sh/message \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-app-token",
    "title": "Report",
    "message": "**Status**: OK\n\n- Task 1: Complete\n- Task 2: Pending"
  }'

Priority Levels

Level	Description	Use Case
-2	Minimum	Debug messages
-1	Low	Info notifications
0	Normal	Regular updates
1	High	Important alerts
2	Maximum	Critical emergencies

Integration Examples

Server Monitoring

Send alerts from monitoring scripts:

#!/bin/bash
PUSHBITS_URL="https://your-pushbits.klutch.sh/message"
TOKEN="your-app-token"

if ! ping -c 1 server.example.com &> /dev/null; then
  curl -X POST "$PUSHBITS_URL" \
    -H "Content-Type: application/json" \
    -d "{
      \"token\": \"$TOKEN\",
      \"title\": \"Server Down\",
      \"message\": \"server.example.com is not responding\",
      \"priority\": 2
    }"
fi

CI/CD Notifications

Notify on build completion:

# In your CI/CD pipeline
- name: Send notification
  run: |
    curl -X POST https://your-pushbits.klutch.sh/message \
      -H "Content-Type: application/json" \
      -d '{
        "token": "${{ secrets.PUSHBITS_TOKEN }}",
        "title": "Build Complete",
        "message": "Build #${{ github.run_number }} finished"
      }'

Cron Job Alerts

# In crontab
0 0 * * * /path/to/backup.sh && curl -X POST https://your-pushbits.klutch.sh/message -H "Content-Type: application/json" -d '{"token":"your-token","title":"Backup","message":"Daily backup complete"}'

API Reference

Send Message

POST /message

Field	Type	Required	Description
token	string	Yes	Application token
title	string	No	Message title
message	string	Yes	Message content
priority	integer	No	-2 to 2

Response

{
  "id": 123,
  "success": true
}

Troubleshooting Common Issues

Notifications Not Arriving

Solutions:

• Verify Matrix bot is in the room
• Check room ID is correct
• Verify Matrix credentials
• Check PushBits logs

Authentication Failed

Solutions:

• Verify application token
• Check admin credentials
• Ensure Matrix password is correct

Matrix Connection Errors

Solutions:

• Verify homeserver URL
• Check network connectivity
• Ensure Matrix account is active

Additional Resources

• PushBits GitHub Repository
• PushBits Documentation
• Matrix.org
• Klutch.sh Deployments

Conclusion

Deploying PushBits on Klutch.sh gives you a self-hosted notification system that respects your privacy while providing reliable delivery through the Matrix network. With a simple API and cross-platform Matrix clients, you can receive notifications on all your devices without depending on proprietary services.

Whether you’re monitoring servers, tracking CI/CD pipelines, or building custom alerting systems, PushBits provides a flexible, privacy-focused solution.