PushizoDocs
Operations

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

ComponentImage / roleNotes
apighcr.io/exec0de/pushizo-api — NestJS + Fastify; /v1, /sdk/v1, /internal, /admin, /hooks, /t/*, /sdk-web/*/healthz, /readyz, /metrics; at least 2 replicas
workerghcr.io/exec0de/pushizo-worker — BullMQ queuesSplit via WORKER_QUEUES: scheduler,audience,dispatch and events,webhooks,journeys,maintenance
migrateghcr.io/exec0de/pushizo-migrateup, down --steps=N, status; runs first during a deploy
dashboardghcr.io/exec0de/pushizo-dashboard — Next.jsAPI_URL, PUBLIC_API_URL, APP_URL
web, docs-siteMarketing site and this documentationSITE_URL, DOCS_SITE_URL build argument
postgres 16Primary data (RLS)Optional PITR with wal-g
redis 7Queues, rate limiting, cacheAOF + hourly RDB
storage (RustFS, S3-compatible)CSV export/import, mediaS3_*; a bucket-scoped service user in production
MonitoringPrometheus, Alertmanager, Grafana, Loki/Promtail, exporters, blackboxStatus and monitoring
OptionalClickHouse (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

VariableDescription
MASTER_KEY32 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/PASSWORDAvoid / + = @ : ? # % in passwords embedded in URLs (openssl rand -hex 32)
SMTP_URL / MAIL_TRANSPORTSystem email
APP_URL, API_URL, PUBLIC_API_URLDomains; 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

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.

On this page