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.
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.
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:
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.
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.
Add and verify pushizo.com in Google Postmaster Tools (domain reputation and spam rate are monitored there).
In the first weeks, send low volumes to real recipients; mark messages that land in spam as Not spam.
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).
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):
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).
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.
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.
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.
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):
Create the dmarc@pushizo.com mailbox in your hosting panel (strong password).
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.
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.
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.
# 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 /swapfileecho '/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 deployinstall -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.pubssh-keyscan github.com >> ~/.ssh/known_hostsgit 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 filecp 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.
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):
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):
Name
Type
Value
pushizo.com (@)
A
server IP
www
A
server IP (nginx redirects to the root domain with 301)
app, api, docs, status, grafana, storage
A
server IP
Don't touch the existing MX/SPF/DKIM/DMARC records. Verify propagation: dig +short app.pushizo.com should return the server IP.
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).
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.
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.
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).
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).
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):
Port
Service
State
22/tcp (or a custom SSH port, e.g. 1981)
SSH
open; ideally only to admin IPs
80/tcp, 443/tcp
HTTP/HTTPS (Plesk nginx → Pushizo)
open
8443/tcp
Plesk panel
open; ideally only to admin IPs
25, 465, 587/tcp
SMTP (incoming mail, submission)
must stay open
993, 143/tcp
IMAP (SSL / plain)
must stay open
995, 110/tcp
POP3 (SSL / plain)
must stay open
4190/tcp
ManageSieve (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.
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.
Then sshd -t && systemctl reload ssh. Without closing the current session, try logging in again with a new session.
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.
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.
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).