GitHub Dashboard →

Introduction

What is VisionPush?

VisionPush is a self-hosted push notification platform for iOS, Android, and Web. You run it on your own server, connect your apps, and send notifications to millions of devices — no per-message fees, no vendor lock-in, full data ownership. It ships as a set of Rust microservices and an Angular admin panel, deployable with a single Docker Compose command for development or a Kubernetes Helm chart for production.

The platform handles the full lifecycle: device registration, audience segmentation, campaign scheduling, multi-platform delivery via APNs, FCM v1, and VAPID, real-time analytics via Apache Parquet and DataFusion, and webhook delivery receipts — all without relying on any third-party notification gateway.

Quick Start

Docker Compose Recommended

Start the full stack locally in one command. Best for development and evaluation.

bash
git clone https://github.com/VisionLab-de/VisionPush.git
cd VisionPush

# Start Postgres, NATS, MinIO, API, Worker, Grafana
docker compose -f infra/docker/docker-compose.yml up -d --build

# Admin panel (hot reload)
cd admin && npm install && npm start
Kubernetes (K3s)

Production-grade deployment with HPA, KEDA, PDB, and NetworkPolicy out of the box.

bash
bash infra/k8s/bootstrap/install.sh
kubectl apply -f infra/k8s/apps/visionpush.yaml

Contents

Document Description
Getting Started Local development setup, prerequisites, first push notification
Architecture System design, data flow, crate overview, NATS streams
Configuration All environment variables for API, Worker, storage, SMTP, and Kubernetes
Deployment — Kubernetes Production K3s + Helm + ArgoCD deployment guide
Deployment — Docker Compose Single VPS deployment without Kubernetes
API Reference REST endpoints, authentication, request/response examples
SDKs iOS (Swift), Android (Kotlin), JavaScript/TypeScript
Observability Metrics, distributed traces, logs, Grafana dashboards, alerts
Security Security architecture, OAuth 2.1, encryption at rest, hardening
Operations Runbook Scaling, backup/restore, incident response procedures

System Overview

architecture
Browser / Mobile App
       │
       ▼
  Admin Panel (Angular)          SDKs (Swift / Kotlin / JS)
       │                                    │
       ▼                                    ▼
  visionpush-api  ────────────────────  /v1/devices
  (Axum REST + OAuth 2.1)               /v1/push/send
       │
       │  NATS JetStream
       ▼
  visionpush-worker
  APNS · FCM v1 · VAPID
       │
       ▼
  visionpush-analytics
  (Parquet + DataFusion)

The API server (visionpush-api) receives requests, authenticates via OAuth 2.1 / OIDC, and publishes campaign jobs to NATS JetStream. The worker (visionpush-worker) consumes those jobs, splits audiences into platform batches, and delivers to APNs, FCM v1, and VAPID concurrently. Delivery results are written to Apache Parquet files and queryable in real time via DataFusion.

Key Capabilities

  • Multi-platform delivery — Apple APNs (HTTP/2, p8 key auth), Google FCM v1 (service account JWT), Web Push VAPID (RFC 8030 + ECE AES-128-GCM)
  • OAuth 2.1 / OIDC 1.0 — embedded auth server with PKCE, refresh token rotation, family theft detection, Argon2id passwords, team invites
  • Parquet + DataFusion analytics — zero-dependency OLAP engine; events stored as ZSTD-compressed Parquet, queried via DataFusion SQL; nightly compaction into daily aggregates
  • NATS JetStream — durable, at-least-once delivery for campaign dispatch, batch processing, and feedback pipelines
  • Kubernetes-native — HPA + KEDA autoscaling, PodDisruptionBudget, NetworkPolicy, CloudNativePG, External Secrets Operator (Vault), ArgoCD
  • Vault secrets management — all production secrets stored at secret/visionpush/production, injected via External Secrets Operator
  • A/B testing — campaign variants with weighted audience splits and per-variant analytics
  • Webhooks — per-app webhook endpoints for sent, delivered, failed, bounced, throttled, expired events with HMAC-SHA256 signatures
  • Frequency capping — per-device limits to prevent notification fatigue
  • In-app messages — server-driven in-app message templates queried by the SDK