Deploy

ZealPHP is a long-lived OpenSwoole server process. One process per port, N workers per process. Run it behind a reverse proxy (nginx, Caddy, HAProxy, Traefik — or Apache as mod_proxy) for TLS termination, static assets, request logging, and horizontal scaling: point the proxy at an upstream pool of ZealPHP backend addresses and it load-balances across them (round-robin / least-conn), exactly as it would across a pool of PHP-FPM or Node services. The built-in HTTP server replaces the per-node web server; the edge proxy is still your load balancer and TLS terminator.

systemd

A reference unit is shipped at deploy/zealphp.service. Copy it to /etc/systemd/system/zealphp.service, adjust User, WorkingDirectory, and ExecStart, then:

sudo systemctl daemon-reload
sudo systemctl enable zealphp
sudo systemctl start zealphp
sudo systemctl status zealphp

# Logs:
sudo journalctl -u zealphp -f

The unit is Type=simple — do not pass -d in ExecStart, systemd manages the lifecycle.

Environment variables

Boolean variables accept 1/0, true/false, on/off, yes/no.

Server

Logging

Middleware & sessions

Site

nginx reverse proxy

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

        # WebSocket upgrades on /ws/*
        proxy_set_header   Upgrade    $http_upgrade;
        proxy_set_header   Connection "upgrade";

        # SSE: disable response buffering and bump timeout
        proxy_buffering    off;
        proxy_read_timeout 86400;
    }
}

Caddy reverse proxy

example.com {
    reverse_proxy 127.0.0.1:8080 {
        flush_interval -1   # streaming SSE / WebSocket
    }
}

Docker

The repo ships a Dockerfile and docker-compose.yml. For production:

services:
  app:
    image: zealphp:0.4.12
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      ZEALPHP_HOST: 0.0.0.0
      ZEALPHP_PORT: 8080
      ZEALPHP_WORKERS: 8
      ZEALPHP_SESSION_SECURE: "1"
    volumes:
      - sessions:/var/lib/php/sessions
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3
volumes:
  sessions:

Production checklist

• Run as a non-root user; bind to 8080, not 80.
• Pin OpenSwoole + ext-zealphp extension versions in your Dockerfile.
• Set ZEALPHP_WORKERS ≈ CPU cores.
• Ensure the session save path (/var/lib/php/sessions) is writable by the service user and mode 0700.
• Disable debug logging in production (ZEALPHP_DEBUG_LOG=0 or unset).
• Set ZEALPHP_MAX_REQUEST (default 100000). Watch for the [recycle] access-log line to confirm the backstop is running.
• Tune OPcache for long-running workers: opcache.validate_timestamps=0 + restart on deploy. Full settings ↗
• Rotate logs in /tmp/zealphp/ with logrotate.
• Behind a TLS-terminating proxy, leave ZEALPHP_SESSION_SECURE unset — the framework auto-detects HTTPS from X-Forwarded-Proto.
• Use php app.php restart to cleanly drain in-flight requests and restart; expect a brief listener-down window between stop and re-bind. For seamless in-place recycling rely on ZEALPHP_MAX_REQUEST worker rotation (workers recycle one-at-a-time after N requests, with no listener downtime). Front the process with a proxy health-check pool for true zero-downtime deploys.

More

Detailed write-up: docs/deployment.md on GitHub.