PushizoDocs
Operations

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.

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.

0. What to prepare (product owner)

#WhatWhereNotes
1DomainAny registrarE.g. pushizo.com
2ServerHetzner / DigitalOcean, etc.Ubuntu 24.04, 4 vCPU / 8 GB RAM / 80 GB SSD to start (plan 08)
3DNS A recordsDomain control panelapi, app, status, docs, grafana, storage subdomains + root/www (marketing site) → server IP
4System emailSMTP / Amazon SES / ResendRequired for sign-up verification and password reset emails; SPF/DKIM/DMARC records
5Apple pushApple Developer → Keys.p8 key, Key ID, Team ID, Bundle ID (entered during app setup in the dashboard)
6Android pushFirebase consoleService account JSON (uploaded during app setup in the dashboard)
7Legal textsLegalPrivacy, Terms of Use, KVKK (Turkish data protection law) Privacy Notice, Cookies — apps/web/content/legal/ (marketing site)
8(Optional) PaymentsStripe or iyzicoWithout one, upgrading to a paid plan is disabled; the platform runs on the free plan and plans assigned from the admin panel

Push and email credentials are not configured on the server; they are entered per app in the dashboard (stored encrypted).

Status for Pushizo (2026-10-16)

  • Domain pushizo.com (DNS on Cloudflare). System email bildirim@pushizo.com, SMTP mta1.mail.tecrube.com:465 (SSL).
  • .env.prod was prepared at the repo root (outside git, .gitignore): pushizo.com addresses, SMTP and randomly generated secret values. It is copied to the server (chmod 600); without Stripe/iyzico, BILLING_PROVIDER=auto keeps paid plan upgrades disabled.
  • GitHub variables: PROD_APP_URL=https://app.pushizo.com, PROD_API_URL=https://api.pushizo.com, PROD_SITE_URL=https://pushizo.com, PROD_DOCS_URL=https://docs.pushizo.com.

Email deliverability (staying out of spam)

In the current DNS, SPF (-all), DKIM (default._domainkey, 2048 bit), DMARC (p=none) and the server PTR (mta1.mail.tecrube.com) are correct. The main cause of spam placement is that the domain is new (registered: 2026-10-16); Gmail/Outlook are cautious with a new domain until it builds reputation (usually 2–4 weeks). To do:

  1. In Gmail, open a received message and choose Show original → SPF, DKIM and DMARC must all be PASS. If DKIM is not PASS, ask your hosting provider to enable DKIM signing for pushizo.com.
  2. DMARC and TLS-RPT reports are received on your own domain (set up on Cloudflare on 2026-10-16): _dmarc → v=DMARC1; p=none; rua=mailto:dmarc@pushizo.com; fo=1, _smtp._tls → v=TLSRPTv1; rua=mailto:dmarc@pushizo.com. The dmarc@pushizo.com mailbox must exist. Reports are monitored on the Email security page of the Pushizo admin panel (see "DMARC reports" below); once SPF/DKIM pass consistently, the panel recommends p=quarantine.
  3. Add and verify pushizo.com in Google Postmaster Tools (domain reputation and spam rate are monitored there).
  4. In the first weeks, send low volumes to real recipients; mark messages that land in spam as Not spam.
  5. A separate subdomain is recommended for the newsletter (haber@pushizo.com) (e.g. haber.pushizo.com), so bulk sending reputation doesn't affect system emails (verification, password reset).

DMARC reports and policy (ADR-0035)

2026-10-30 — email infrastructure on flanque: pushizo.com MX, SPF (include:spf.flanque.com), DKIM and DMARC (p=quarantine; rua=mailto:dmarc@flanque.com) were connected to the flanque mail system (user decision). In the dmarc@pushizo.com steps below, dmarc@flanque.com on flanque's Postal plays the same role as that mailbox: the HTTP endpoint route https://api.pushizo.com/hooks/dmarc/<token> is defined there; TLS-RPT (_smtp._tls) still goes to dmarc@pushizo.com.

DMARC aggregate reports and TLS-RPT reports arrive at dmarc@pushizo.com. Pushizo stores them, classifies sending sources as authorized / unauthorized, emails platform admins when a new unauthorized source appears or the pass rate drops (once per day per source/alert), and after 14 days with a 98% pass rate recommends tightening the policy by one step (none → quarantine → reject). Panel: https://app.pushizo.com/admin/email-security.

Set up one of two ways (or both) to receive reports:

A) Postal HTTP Endpoint (recommended; the pushizo.com MX is on Postal):

  1. Generate a token: openssl rand -hex 24 (48 characters). Set DMARC_INBOUND_TOKEN=<token> in .env.prod; restart the API (docker compose --env-file .env.prod -f infra/compose/docker-compose.prod.yml up -d api worker).
  2. Postal panel (panel.mail.tecrube.com) → pushizo.com server → Routing → HTTP Endpoints → Add: URL https://api.pushizo.com/hooks/dmarc/<token>, Encoding: Body as JSON, Format: Raw message, Strip replies off.
  3. Routing → Routes → Add route: Name dmarc, Domain pushizo.com, Endpoint = the HTTP endpoint from step 2, Mode Endpoint. This way, no separate mailbox is needed for dmarc@pushizo.com.
  4. Keep Postal's incoming mail spam checking on (server setting Spam checking: SpamAssassin, threshold ~5). Messages that aren't reports (spam) are accepted by Pushizo with 200 and discarded; Postal does not retry. Body limit 25 MB, rate limit 120 requests per minute per IP; a wrong token returns 404.
  5. Verification: curl -s -o /dev/null -w '%{http_code}' -X POST https://api.pushizo.com/hooks/dmarc/yanlis -H 'content-type: application/json' -d '{}' → 404. The first reports arrive within 24–48 hours (Google, Microsoft, Yahoo).

B) IMAP mailbox (if a Postal route can't be set up):

  1. Create the dmarc@pushizo.com mailbox in your hosting panel (strong password).
  2. In .env.prod, set DMARC_IMAP_URL=imaps://dmarc%40pushizo.com:<URL-encoded password>@<imap-server>:993 (if the password contains @ : / ? # %, URL-encode it: node -e "console.log(encodeURIComponent(process.argv[1]))" '<password>'). Restart the worker.
  3. The worker scans the mailbox every 15 minutes (single run enforced by a Redis lock): reports are read and moved to the Processed folder (created if missing), and non-report messages are moved to the trash. You can trigger it immediately with Scan now in the panel.

One-click policy with Cloudflare (optional): Cloudflare → My Profile → API Tokens → Create Token → the "Edit zone DNS" template, Zone Resources = pushizo.com only. In .env.prod, set CLOUDFLARE_API_TOKEN=<token>, CLOUDFLARE_ZONE_ID=\<the Zone ID on the pushizo.com Overview page>; restart the API. In the panel, Apply with Cloudflare changes only the p= tag (rua and fo are preserved), the action is written to the platform audit log, and Undo restores the previous value. If Cloudflare isn't configured, the panel shows the full TXT value to enter; update the record manually in Cloudflare.

1. GitHub settings (once)

Settings → Secrets and variables → Actions (private repo: github.com/exec0de/pushizo):

  • Secrets: PROD_SSH_HOST (server IP or hostname), PROD_SSH_USER (deploy user, e.g. deploy), PROD_SSH_KEY (this user's private SSH key; its public key goes in ~/.ssh/authorized_keys on the server).
  • Variables: PROD_APP_URL=https://app.pushizo.com, PROD_API_URL=https://api.pushizo.com, PROD_SITE_URL=https://pushizo.com, PROD_DOCS_URL=https://docs.pushizo.com, DEPLOY_PATH=/opt/pushizo. Optional: PROD_INDEXNOW_KEY, PROD_CONTACT_EMAIL (contact address on the site, e.g. bildirim@pushizo.com).
  • Staging: if you have no separate staging server, define nothing; while STAGING_ENABLED is undefined the staging job is skipped and the production deploy goes straight to approval. To use staging, set STAGING_ENABLED=true + the STAGING_SSH_HOST/USER/KEY secrets + the STAGING_APP_URL, STAGING_API_URL variables.
  • Settings → Environments → production: required reviewer (production deploys are approved manually).

2. Server preparation (once)

# On the server (root or sudo):
apt-get update && apt-get install -y docker.io docker-compose-v2 git ufw
# Firewall (only on servers WITHOUT Plesk): SSH, HTTP, HTTPS. Don't use ufw on a Plesk server: §9.1.
ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp && ufw --force enable
# Swap on servers with less than 8 GB RAM (4 GB is enough for a single server without Postgres/ClickHouse)
fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
# Deploy user (GitHub Actions connects over SSH as this user)
adduser --disabled-password --gecos "" deploy && usermod -aG docker deploy
install -d -o deploy -g deploy -m 700 /home/deploy/.ssh
# Add the public key of PROD_SSH_KEY to /home/deploy/.ssh/authorized_keys (mode 600, owned by deploy).
install -d -o deploy -g deploy /opt/pushizo

Because the repo is private, it is cloned with a deploy key and images are pulled with a GHCR login (both as the deploy user):

sudo -iu deploy
# 1) Read-only deploy key: add the public key under GitHub → repo → Settings → Deploy keys ("Allow write access" off).
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519 -C "pushizo-deploy" && cat ~/.ssh/id_ed25519.pub
ssh-keyscan github.com >> ~/.ssh/known_hosts
git clone git@github.com:exec0de/pushizo.git /opt/pushizo && cd /opt/pushizo
# 2) GHCR: only with a GitHub PAT (classic) scoped to `read:packages`; the password is read from stdin and not written to history.
docker login ghcr.io -u <GITHUB_KULLANICI_ADINIZ> --password-stdin
# 3) Environment file
cp infra/compose/.env.prod.example .env.prod && chmod 600 .env.prod

Fill in the following in .env.prod: SMTP_URL (password URL-encoded), secret values (MASTER_KEY 32 bytes base64, SESSION_SECRET at least 32 characters, POSTGRES_*, REDIS_PASSWORD, STORAGE_ROOT_*, S3_ACCESS_KEY/S3_SECRET_KEY, GRAFANA_ADMIN_PASSWORD) and separate BACKUP_S3_ACCESS_KEY/BACKUP_S3_SECRET_KEY for backups. For random values use openssl rand -hex 32 (only 0-9a-f). POSTGRES_PASSWORD and REDIS_PASSWORD are embedded in the DATABASE_URL/REDIS_URL addresses: / + = from base64 output (or @ : ? # %) break the address, and deploy.sh stops the deploy with an explicit message in that case (the value is not printed). MASTER_KEY is the exception: it must be 32 bytes base64 (the command in the example file). Domains are pre-filled as pushizo.com in the example. PROVIDER_MODE=real and ALLOW_MOCK_PROVIDERS=false must stay as they are; ADMIN_MFA_REQUIRED defaults to true (turning it off is a deliberate decision; GO_LIVE_CHECKLIST.md). In production, a short SESSION_SECRET, the development S3 password and a localhost SMTP address are rejected (the application won't start).

For alert emails (Alertmanager), the SMTP password is written to a separate secret file (the deploy scripts create it empty if it doesn't exist; while it is empty, no alert emails are sent). Slack is optional: if secrets/slack_webhook_url is filled in, Slack is enabled too.

install -d -m 700 infra/compose/secrets
read -rs -p "SMTP parolası: " P && printf '%s' "$P" > infra/compose/secrets/smtp_password; unset P; echo

The directory is 700; the scripts set the file mode to 644 (the Alertmanager container reads it as the nobody user).

Changing a URL-unsafe password on an installed system: the Postgres role password is only set on the first installation (empty data directory); changing .env.prod alone is not enough. Generate a new value with openssl rand -hex 32 and update it first in the database, then in the file (the password is not written to the command line/history):

cd /opt/pushizo
read -rs -p "Yeni pushizo parolası: " P; echo
printf "alter role pushizo password '%s';\n" "$P" | docker compose --env-file .env.prod -f infra/compose/docker-compose.prod.yml \
  exec -T postgres psql -U postgres -d pushizo -v ON_ERROR_STOP=1 >/dev/null; unset P
# .env.prod → POSTGRES_PASSWORD=<same value> (with nano/vim), then: IMAGE_TAG=<version> ./infra/scripts/deploy.sh prod

REDIS_PASSWORD is only changed in .env.prod; deploy.sh recreates Redis and the applications with the new value.

3. DNS

On Cloudflare (pushizo.com), point the following A records to the server IP; the proxy status must be DNS only (grey cloud) (Let's Encrypt HTTP validation and nginx TLS run directly on the server):

NameTypeValue
pushizo.com (@)Aserver IP
wwwAserver IP (nginx redirects to the root domain with 301)
app, api, docs, status, grafana, storageAserver IP

Don't touch the existing MX/SPF/DKIM/DMARC records. Verify propagation: dig +short app.pushizo.com should return the server IP.

4. Release tag → images

GitHub Actions automatic triggers are disabled (2026-10-19, cost). Pushing a tag no longer starts the workflow. The recommended path is to build and deploy on the server without Actions (LOCAL_BUILD=1 in .env.prod): cd /opt/pushizo && git fetch --tags && git checkout -q vX.Y.Z && ./infra/scripts/deploy.sh prod. If you want GHCR images and a GitHub Release, run it manually via GitHub → Actions → release → "Run workflow", selecting the vX.Y.Z tag in the "Use workflow from" field.

On the developer machine (the version must match package.json, apps/api/src/version.ts and CHANGELOG.md):

git tag v1.0.0 && git push origin v1.0.0

release.yml pushes the images to GHCR (ghcr.io/exec0de/pushizo-*:1.0.0, tag without the v prefix) and creates a GitHub Release. The production deploy job waits for production approval: don't approve it until step 5 is done (nginx won't start without certificates).

5. TLS and first deploy (on the server, as the deploy user)

cd /opt/pushizo && git fetch --tags && git checkout -q v1.0.0
IMAGE_TAG=1.0.0 ./infra/scripts/certbot-init.sh   # Let's Encrypt certificates for all domains + www
IMAGE_TAG=1.0.0 ./infra/scripts/deploy.sh prod    # migrate → api-1/api-2 → workers → dashboard/docs/web → nginx

Then approve the production deploy in GitHub Actions: it re-applies the same version (idempotent) and runs the smoke test (/healthz version, status.json, dashboard). For later releases, you only push a tag and approve.

6. First sign-in and admin

  1. Create an account at https://app.pushizo.com/register and verify your email.
  2. Make the account a platform admin (on the server, once):
    docker compose --env-file .env.prod -f infra/compose/docker-compose.prod.yml exec postgres \
      psql -U postgres -d pushizo -c "update accounts set is_platform_admin = true where lower(email) = lower('SENIN@EPOSTAN');"
  3. Go to https://app.pushizo.com/admin (if MFA is on, first set up My account → two-factor authentication).

7. Connecting the first app and your applications

In the dashboard, New app → choose a platform → .p8 / Firebase JSON / site URL → verification → add the provided SDK code to your application → once the first subscriber arrives, send a test notification. When migrating from a previous provider, subscribers are imported via Data → Import → previous provider CSV; run both systems in parallel for a few days, then shut down the previous provider.

8. After launch

  • https://status.pushizo.com and Grafana dashboards (https://grafana.pushizo.com); alerts in infra/monitoring (email: bildirim@pushizo.com).
  • Backups: sudo bash infra/scripts/install-cron.sh (once; idempotent) → /etc/cron.d/pushizo runs backup.sh daily at 03:30 (PostgreSQL pg_dump + RustFS object storage mirror → off-server bucket; walg-backup.sh at 03:00 if wal-g is enabled), log /var/log/pushizo-backup.log (logrotate weekly, 8 copies), freshness metric /var/lib/node_exporter/textfile/pushizo_backup_*.prom → the PushizoBackupStale alert fires after 26 hours. The AWS CLI is not installed on the host (pinned amazon/aws-cli image, AWS_CLI_IMAGE). Try the first backup right away: sudo /opt/pushizo/infra/scripts/backup.sh and run a restore drill (docs/runbooks/restore.md).
  • Search engines: docs/guides/seo.md (Search Console, sitemap).

9. Server with Plesk (EDGE_MODE=plesk)

Ports 80/443 and TLS are handled by Plesk's nginx; the Pushizo nginx container only listens on 127.0.0.1:EDGE_PORT (18080) (infra/compose/docker-compose.plesk.yml). Domains and certificates are set up with sudo ./infra/scripts/plesk-setup.sh (upload limit 64 MB, same as Pushizo's nginx). With LOCAL_BUILD=1, images are built on the server; after a successful deploy, deploy.sh removes unused images older than a week and build cache beyond 10 GB. If the LOCAL_BUILD=true variable is defined on GitHub, deploys don't depend on GHCR images (release.yml).

9.1 Firewall (Plesk Firewall)

Don't write ufw/iptables rules by hand on a Plesk server: Plesk Firewall overwrites or conflicts with them, and mail/panel access can be cut off. Manage it through Tools & Settings → Firewall (Plesk Firewall extension):

PortServiceState
22/tcp (or a custom SSH port, e.g. 1981)SSHopen; ideally only to admin IPs
80/tcp, 443/tcpHTTP/HTTPS (Plesk nginx → Pushizo)open
8443/tcpPlesk panelopen; ideally only to admin IPs
25, 465, 587/tcpSMTP (incoming mail, submission)must stay open
993, 143/tcpIMAP (SSL / plain)must stay open
995, 110/tcpPOP3 (SSL / plain)must stay open
4190/tcpManageSieve (mail filters)must stay open

EDGE_PORT (18080) and container ports (Postgres, Redis, Grafana, Prometheus) are not exposed externally: compose doesn't publish them, and nginx binds only to 127.0.0.1. Docker manages its own iptables chains; don't delete "Docker"-related rules in Plesk Firewall. When applying a change, Plesk asks for confirmation within 60 seconds; if access is lost, the rules are rolled back automatically.

9.2 SSH hardening (manual; the scripts don't change SSH settings)

  1. First verify that key-based login works in a separate session (ssh -i ~/.ssh/<key> <user>@<server>); the deploy user's ~/.ssh/authorized_keys file must contain the GitHub Actions public key.
  2. In /etc/ssh/sshd_config.d/99-pushizo.conf:
    PasswordAuthentication no
    KbdInteractiveAuthentication no
    PermitRootLogin prohibit-password
    PubkeyAuthentication yes
    Then sshd -t && systemctl reload ssh. Without closing the current session, try logging in again with a new session.
  3. If you use a custom SSH port (e.g. 1981), open it in Plesk Firewall; for PROD_SSH_HOST on GitHub you need ~/.ssh/config or -p in the workflow; if the port wasn't changed, it stays 22.
  4. fail2ban: Plesk → Tools & Settings → IP Address Banning (Fail2Ban) → Enable intrusion detection; the plesk-ssh (or ssh) jail must be enabled. GitHub Actions egress IPs vary: if failed logins get blocked, check the jail (fail2ban-client status sshd) and add your admin IP to the "Trusted IP Addresses" list.

9.3 Backups and monitoring

  • sudo bash infra/scripts/install-cron.sh → /etc/cron.d/pushizo (03:30 backup) and /etc/logrotate.d/pushizo; these don't appear in Plesk's own "Scheduled Tasks" screen; check them with cat /etc/cron.d/pushizo.
  • The Prometheus internal nginx probe (http://nginx/nginx-health) works in Plesk mode as well (port 80 is listened on inside the container, not published externally); external probes monitor all domains, including www, grafana, storage, and certificate expiry (Plesk Let's Encrypt).

On this page