Self-hosting
Options for running Pushizo on your own infrastructure — single-server Docker Compose and Kubernetes Helm; components, system requirements, environment variables, images, upgrades and a backup overview.
Pushizo is distributed as an open monorepo and offers two deployment paths: Docker Compose (single server, nginx + Let's Encrypt, monitoring and backups included) and Helm (Kubernetes; blue/green API, worker scaling with KEDA, NetworkPolicy, ExternalSecrets). The production SaaS (pushizo.com) runs on the same images.
Components
| Component | Image / role | Notes |
|---|---|---|
api | ghcr.io/exec0de/pushizo-api — NestJS + Fastify; /v1, /sdk/v1, /internal, /admin, /hooks, /t/*, /sdk-web/* | /healthz, /readyz, /metrics; at least 2 replicas |
worker | ghcr.io/exec0de/pushizo-worker — BullMQ queues | Split via WORKER_QUEUES: scheduler,audience,dispatch and events,webhooks,journeys,maintenance |
migrate | ghcr.io/exec0de/pushizo-migrate | up, down --steps=N, status; runs first during a deploy |
dashboard | ghcr.io/exec0de/pushizo-dashboard — Next.js | API_URL, PUBLIC_API_URL, APP_URL |
web, docs-site | Marketing site and this documentation | SITE_URL, DOCS_SITE_URL build argument |
postgres 16 | Primary data (RLS) | Optional PITR with wal-g |
redis 7 | Queues, rate limiting, cache | AOF + hourly RDB |
storage (RustFS, S3-compatible) | CSV export/import, media | S3_*; a bucket-scoped service user in production |
| Monitoring | Prometheus, Alertmanager, Grafana, Loki/Promtail, exporters, blackbox | Status and monitoring |
| Optional | ClickHouse (analytics), Kafka (event ingest), Go dispatcher (push delivery) | Runbooks |
System requirements (starting point)
Single server: Ubuntu 24.04, 4 vCPU / 8 GB RAM / 80 GB SSD; DNS A records for api, app, status, docs, grafana, storage and the root/www. System email (SMTP/SES/Resend) is required for sign-up verification and password resets; push/email provider credentials are not configured on the server but entered per app in the dashboard.
Required secrets
| Variable | Description |
|---|---|
MASTER_KEY | 32 bytes, base64; the root of envelope encryption for all provider credentials. Losing it is unrecoverable; for rotation see the runbook |
SESSION_SECRET | ≥ 32 characters |
POSTGRES_PASSWORD, REDIS_PASSWORD, STORAGE_ROOT_USER/PASSWORD | Avoid / + = @ : ? # % in passwords embedded in URLs (openssl rand -hex 32) |
SMTP_URL / MAIL_TRANSPORT | System email |
APP_URL, API_URL, PUBLIC_API_URL | Domains; TRUST_PROXY when behind a proxy |
The production environment check rejects weak/default values (the development S3 password, local SMTP, a short SESSION_SECRET); the application role must be NOSUPERUSER NOBYPASSRLS (Postgres roles).
Installation paths
Deploying with Docker Compose
Step by step: preparation, GitHub settings, server, DNS, TLS, first deploy, Plesk edge mode.
Kubernetes with Helm
Prerequisites, values, blue/green, KEDA, NetworkPolicy, ExternalSecrets, verification.
Backup and restore
Daily base backup, wal-g PITR, Redis and object storage recovery, drills.
Status and monitoring
status.json, synthetic monitoring, metrics, alerts, Grafana dashboards.
Upgrades
A release tag (vX.Y.Z) builds the images through the GitHub Actions release.yml workflow; on the server, IMAGE_TAG=X.Y.Z ./infra/scripts/deploy.sh prod updates services in order migrate → api-1 → api-2 → workers → dashboard/docs/web (zero downtime). Migrations are backward compatible and include down; to roll back, run migrate down --steps=1 and use the previous image tag. For installations that don't want a private registry/GHCR credentials, LOCAL_BUILD=1 builds the images on the server.
Multi-region (cells)
For data regions such as EU/TR, each cell is a complete installation; the control plane keeps the org → cell mapping (cells runbook, data residency).
Platform admin panel
The panel under /admin manages organizations, accounts, billing, feature flags, abuse, support sessions, incidents (status page), app transfer approvals, system health, the DLQ and the audit log; MFA is mandatory (ADMIN_MFA_REQUIRED). Setting up the first admin: Deploying with Compose → First sign-in.
Security review — OWASP ASVS 4.0 (Level 2) checklist (Phase 14)
Date: 2026-10-13. Scope: API (apps/api), worker, dashboard, SDK endpoints, data layer. Each item is tied to evidence verified in the code (file/test); "partial"/"open" items are tracked before go-live in GO_LIVE_CHECKLIST.md.…
Pushizo — Going live (step by step)
This document covers the first production installation on a single server (Docker Compose). The detailed checklist is GO_LIVE_CHECKLIST.md, infrastructure details are in infra/README.md. For Kubernetes, see docs/runbooks/helm-production.md.