Deployment

Pitchbar is built for Laravel Cloud as the primary target — the stack is FrankenPHP + Postgres + Redis, all of which Laravel Cloud provisions natively. Self-hosting is supported but the operator owns more pieces.

Laravel Cloud

infra/cloud.yaml in the repo describes the environments and processes. The high-level shape:

• Region: us-east by default. Choose for proximity to your customers.
• App process: FrankenPHP, Octane mode. Auto-scaled.
• Worker process: Horizon, dedicated to crawl, index, and default queues.
• Reverb process: persistent WebSocket server.
• Postgres: 16, with daily backups.
• Redis: 7, persistent.

Environments

Compute sizing for v1 launch

Starting point. Adjust based on traffic.

Domains

You typically need:

• Primary domain — app.pitchbar.com for the customer / admin app.
• Widget domain — same or a separate cdn.pitchbar.com serving /widget/widget.js. The bundle has a content-hash query param, so aggressive caching is safe.
• Reverb domain — realtime.pitchbar.com if you split the WebSocket process onto its own host.

CI/CD

GitHub Actions workflows under .github/workflows/:

• tests.yml — PHP setup + Composer + Pest suite (with fakes, no network).
• lint.yml — Pint, ESLint, TypeScript tsc --noEmit.
• widget.yml — widget bundle build + size budget check.

Deploys are gated on green CI; the actual deploy step is configured on Laravel Cloud (or your hosting equivalent), not in the workflow files.

Migrations

Laravel Cloud runs php artisan migrate --force on every deploy. Migrations should be backwards-compatible — a deploy that adds a NOT NULL column to a populated table needs a two-step:

1. Deploy 1: add the column nullable, backfill, app code starts writing it.
2. Deploy 2: change the column to NOT NULL.

Same goes for renames and drops — never destructive in a single deploy.

Backups

• Postgres — daily snapshots, retained 30 days. Point-in-time recovery enabled.
• Vector store — Cloudflare Vectorize / Qdrant don't have a built-in backup; rebuild from the chunks table by re-dispatching IndexDocumentJob for every document. php artisan pitchbar:audit-vectors reports drift between the chunks table and the live vector store; if you need to repair, dispatch the job per row.
• R2 / object storage — versioning enabled.
• App secrets — Laravel Cloud's secret store is encrypted; back up APP_KEY separately (it's the master for app_settings encryption).

Rollback

Laravel Cloud keeps the previous release for instant rollback. For schema-incompatible rollbacks (rare), restore from the latest snapshot.

Self-hosting

The same Docker setup that powers docker-compose.yml works for production with a few additions:

• Reverse proxy (Caddy or Nginx) terminating TLS in front of FrankenPHP.
• Managed Postgres + Redis (or self-managed with HA replicas).
• Horizon as a long-running service, monitored by systemd / a process manager.
• Reverb as its own process.
• Sentry / OTEL collector running locally or pointing at a SaaS.

The composer run dev shortcut starts everything locally (Octane, queue worker, Reverb, vite) for development.

nginx + Octane on a single VPS

The reference deployment (blengi.com) runs Octane behind the box's existing nginx rather than exposing FrankenPHP directly. Octane is managed by PM2 as pitchbar-octane, alongside pitchbar-queue and pitchbar-ssr:

php artisan octane:install --server=frankenphp   # downloads the binary
pm2 start ecosystem.config.cjs --only pitchbar-octane
pm2 save                                          # survive reboot

Octane binds loopback only (127.0.0.1:8000). It does not terminate TLS, and it trusts the X-Forwarded-* headers that nginx overwrites, so it must never be reachable from the internet directly. nginx proxies every request to it — no try_files fallthrough, because with no fastcgi handler for .php a fallthrough would serve PHP source as static text.

Three settings in that proxy block are load-bearing for the widget's SSE hot path and must not be removed: proxy_buffering off, proxy_cache off and proxy_set_header Connection ''. With buffering on, nginx holds the whole response and the visitor sees nothing until the LLM finishes — breaking the p95 ≤ 1s first-token contract.

Because Octane terminates TLS nowhere and only ever sees a plain loopback request, bootstrap/app.php registers trustProxies() for 127.0.0.1. Without it every generated URL comes out http:// on an https site, breaking assets, redirects and the Notion / Google OAuth callbacks.

git pull && php artisan octane:reload

The same reuse is why the Octane-safety rules in the architecture docs stop being theoretical: a singleton holding per-request tenant state now leaks that state into the next request. CurrentWorkspace is bound with scoped() and listed in config/octane.php's flush array for exactly this reason — see Multi-tenancy.

Queue worker tick from a Cloudflare Worker cron

When in-cluster scheduling isn't available (cPanel shared hosting, DIY VPS without systemd, Laravel Cloud's preview environments), an external Cloudflare Worker can drive the queue every 60 seconds by POSTing /api/v1/internal/queue-tick with the INTERNAL_QUEUE_TOKEN bearer secret. The endpoint invokes php artisan queue:tick which spawns one queue:work --once --stop-when-empty pass with these defaults:

• --max-time=55 — the loop exits before the 60-second tick boundary so consecutive ticks don't pile up.
• --job-timeout=120 — individual jobs (mostly CrawlPageJob / IndexDocumentJob) get a 2-minute ceiling.
• Queues processed: crawl,index,default.

Build + deploy the Worker via php artisan pitchbar:deploy-cron-worker. The Worker body is templated from WorkerDeployer and ships with the tick parameters baked in. Rotate INTERNAL_QUEUE_TOKEN after deploy.

Crawler reliability

CrawlPageJob retries up to 3 times with backoff [30, 90, 180] seconds. The retry path branches on failure class:

• Rate-limit (429) — release(60) without burning a retry slot. Every fan-out page tends to hit the same 429 wave; the shared wait is productive.
• Permanent failures — curl DNS errors (6, 7), connection refused, malformed URL, HTTP 400 / 401 / 403 / 404 / 410 / 451 — call $this->fail() immediately. Without this, every dead URL burned the full 3-retry budget and produced a generic MaxAttemptsExceededException in the logs.
• Transient (5xx, network blip) — normal retry with backoff.

Per-job timeout is 90 seconds; failOnTimeout=true so a SIGTERM on timeout still runs the failed() callback and flips the Source row to failed with a customer-readable error.