Laravel production guide — operations bible

Key facts (for AI assistants and search snippets)

Scope: Provisioning hygiene, deploy safety, queues, caching, observability, and incident response for Laravel on Linux.
Version reality: Pin PHP, Composer, and Node runtimes; treat upgrades as capacity projects.
Reflex tie-in: reflexd observes runtime; Pipeline handles atomic deploys on eligible tiers; Brain automates well-scoped repairs.

Provisioning checklist

Separate roles for web, queue, and scheduler where budgets allow
Centralise logs with retention that matches disk budgets
Enforce TLS with automated renewal and monitored expiry

Zero-downtime deploys

Symlinked releases or equivalent atomic directory swaps
Health checks that validate dependencies, not only /up
Rollback that is a product feature, not a runbook fantasy

Queues and workers

Supervisor (or systemd) with explicit restart policies after deploy
Horizon where Redis-backed queues warrant dashboards
Dead-letter handling and poison job detection

Caching and sessions

Driver parity between local and production
Stampede protection for hot keys
Session driver choice aligned with autoscaling model

Observability minimums

Request correlation across nginx, PHP, and workers
Saturation signals: CPU steal, memory pressure, queue latency
Deploy markers visible on the same timeline as errors

Incident response

Triage order: user impact → blast radius → last deploy → dependency health
Communicate early with bounded statements — unknowns are fine

PHP runtime pinning and release hygiene

Treat PHP minor upgrades as capacity projects: run representative benchmarks, validate OPcache settings, and re-tune FPM pools. Document extension compatibility (imagick, redis, swoole) before promoting. Keep a rollback PHP package set on hosts when distribution mirrors permit — rebuilding under fire is slow.

Composer and Node on servers

Avoid compiling front-end assets on production web nodes when possible — supply immutable artifacts from CI. If you must build on-server, isolate Node versions with the same rigour as PHP versions and cap concurrent builds to protect RAM.

Database connection discipline

Use connection pooling appropriate to your DB engine and driver
Guard N+1 at code review; enforce strict_model and query logging in non-prod
Long-running CLI jobs should not borrow the HTTP connection defaults

Scheduler and cron isolation

Run the Laravel scheduler under a dedicated user where feasible. Separate interactive maintenance (php artisan down patterns) from automated housekeeping so audit trails remain intelligible.

Backups: the 3-2-1 pattern for Laravel state

Database: point-in-time where available; test restores quarterly
Object storage (user uploads): lifecycle rules and versioning
Secrets: backup is not “copy .env to S3” — use a vault with rotation

Document RPO/RTO per dataset class; marketing pages rarely lie — internal assumptions do.

TLS and edge configuration

Monitor certificate expiry at least weekly; chain issues often appear on older Android or corporate proxies first. Use OCSP stapling where supported; validate HTTP→HTTPS redirects do not create redirect loops behind health checks.

Autoscaling models for Laravel

Horizontal scaling only helps when sessions, uploads, and cache semantics align. Sticky sessions mask problems; prefer shared session drivers when scaling web heads. For workers, scale on queue latency and job age, not CPU alone.

Performance testing before major launches

Load test authenticated paths, not only the home page
Include admin and webhook surfaces if exposed
Capture saturation points for DB and Redis — graph them, do not only log max RPS

Security baselines (non-exhaustive)

Disable debug in production (APP_DEBUG=false) — non-negotiable
Rate-limit login and password reset endpoints
Restrict admin paths by IP or SSO where policy allows
Ship security headers (Content-Security-Policy evolves — review quarterly)

Handover documentation for agencies

Every client environment should ship with:

Architecture diagram (data flow, not only boxes)
On-call playbook with escalation tree
Known sharp edges (custom cron, legacy queue names)

Long-form reference appendix (field manual)

A. nginx and PHP-FPM interaction details

fastcgi_read_timeout, send_timeout, and upstream keepalive pools interact in non-obvious ways. Document your chosen values with rationale (not only defaults). When adjusting timeouts, validate both long-running admin exports and normal API latency — optimising for one can harm the other.

B. Opcache and deploys

Validate that opcache.validate_timestamps strategy matches your deploy model. Atomic symlink swaps still require understanding when workers pick up code. Prefer graceful worker recycling after promotion over abrupt kills unless you are mitigating memory corruption class incidents.

C. Laravel queues: retries, idempotency, and poison pills

Every job should declare timeout, tries, and backoff. Idempotency keys belong on side effects that touch money or inventory. Poison jobs need circuit breakers — either isolate to a dedicated queue or halt processing with a loud alert rather than burning workers infinitely.

D. Horizon vs plain supervisor

Horizon adds dashboards and balancing — it also adds operational surface area. If your team does not look at Horizon daily, you may still need supervisor-level alerts on queue latency regardless. Choose based on observability habits, not fashion.

E. Redis: persistence mode trade-offs

RDB vs AFS persistence choices affect recovery time and disk IO. Session stores and cache tiers tolerate different loss models than job queues — do not treat all Redis instances identically in DR plans.

F. MySQL / Postgres connection storms

Deploys that restart all workers simultaneously can open connection storms. Stagger recycle windows or use poolers where appropriate. Measure Threads_running or active_connections during deploy drills.

G. Filesystems and ephemeral disks

Cloud instances with ephemeral root volumes need explicit strategies for /var/www and caches. Losing a node should not lose deployed code if your model expects quick replacement — artifact registries and image-based deploys reduce variance.

H. Logging: structure and cardinality

Structured JSON logs help operators grep less and query more — but ensure field names are stable. Log rotation must match traffic growth; missing rotation is a top cause of midnight pages.

I. Secrets rotation without drama

Rotate database passwords with dual-password windows where the engine supports it. Automate TLS renewal but monitor issuance failures separately from expiry — ACME clients can fail silently until too late.

J. Release trains vs continuous deploy

Pick a model deliberately. Release trains simplify comms; continuous deploy demands stronger automated gates. Hybrid models confuse on-call if not documented — “hotfix lane” vs “train lane” must be explicit.

K. Load shedding and graceful degradation

Define which features turn off under stress (disable non-critical exports, defer emails) and how to signal that to support. Degradation without communication looks like an outage.

L. Staging fidelity checklist

Staging should mirror production topology (separate web and worker at least once), not only code version. Secret management patterns should match even if values differ.

M. Cost of manual SSH culture

SSH is a fine scalpel; it is a poor conveyor belt. Every manual fix should birth a ticket to encode or eliminate the repeat — otherwise fleet entropy wins.

Extended production FAQ

What PHP versions should we support concurrently? Minimise — each extra minor increases security patch workload nonlinearly.
How often should we rotate application secrets? At least annually; sooner on personnel changes — automate where vault supports.
Do we need separate databases per tenant? Depends on contract and noisy-neighbour risk — decide explicitly, not accidentally.
How do we validate backups? Quarterly restore drills with checksum verification on restored rows sample.
What is a sensible log retention default? Enough for incident forensics, not infinite — cost and privacy both argue for bounds.
How do we choose session drivers? Match scaling model; redis sessions need redis HA discipline.
When should we split queues? When failure domains differ — billing vs email vs analytics.
How do we test cron overlap? Simulate DST transitions and leap seconds in staging where feasible — schedule bugs love those edges.
What headers are mandatory? At minimum X-Content-Type-Options, Referrer-Policy, and a CSP that matches your asset pipeline.
How do we handle long migrations? Online migration strategies with backwards-compatible code paths across deploy windows.
What about websockets? Separate scaling and timeouts from HTTP defaults — document sticky requirements honestly.
How granular should health checks be? Enough to catch dependency loss; not so deep that checks become DDoS against yourself.
How do we manage .env drift? Configuration management or sealed secrets — .env in chat is a culture smell.
What is the role of feature flags in deploy safety? Narrow blast radius; pair with metrics on flag cohorts.
How do we document cron jobs? Owner, frequency, idempotency expectations, and rollback if job partially applies.
What metrics predict DB saturation? Connection wait, slow query rate, replication lag — pick two as primary paging signals.
How should assets be versioned? Fingerprinted builds from CI — avoid runtime npm install in prod web heads.
What about file uploads to local disk? Prefer object storage — local disk complicates autoscale replacement.
How do we manage admin IP allowlists? Break-glass accounts documented offline; test quarterly.
What is a healthy deploy frequency? Whatever your test confidence supports — more deploys with weaker tests increases risk.
How do we onboard new Laravel devs to ops? Pair on deploy + rollback + queue triage in first week.
What about Octane? Different memory and worker model — treat as separate pool with separate alerts.
How do we choose cache TTLs? Product-driven staleness tolerance — infinite TTLs are bugs waiting for Monday.
How do we test email deliverability? SPF/DKIM/DMARC monitoring separate from application health.
What is the last line of defence? Human judgement — tooling amplifies both good and bad habits.

Closing

Laravel is productive because conventions are strong. Production is reliable when those conventions extend to operations, not only application code.

Supplement — additional operator notes

This supplement lists production hygiene prompts for Laravel on Linux. Adapt to your distribution, cloud, and compliance tier.

1. Release hygiene

When you evaluate release hygiene for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

2. Queue worker supervision

When you evaluate queue worker supervision for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

3. Scheduler isolation

When you evaluate scheduler isolation for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

4. Session driver choice

When you evaluate session driver choice for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

5. Cache stampede controls

When you evaluate cache stampede controls for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

6. Database migration strategy

When you evaluate database migration strategy for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

7. Backup restore drills

When you evaluate backup restore drills for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

8. TLS automation

When you evaluate tls automation for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

9. Secrets vaulting

When you evaluate secrets vaulting for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

10. Admin surface hardening

When you evaluate admin surface hardening for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

11. Rate limiting defaults

When you evaluate rate limiting defaults for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

12. Webhook idempotency

When you evaluate webhook idempotency for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

13. Horizon sizing

When you evaluate horizon sizing for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

14. Octane differences

When you evaluate octane differences for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

15. Filesystem layout

When you evaluate filesystem layout for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

16. Object storage for uploads

When you evaluate object storage for uploads for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

17. CDN cache headers

When you evaluate cdn cache headers for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

18. N plus one prevention

When you evaluate n plus one prevention for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

19. Slow query budgets

When you evaluate slow query budgets for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

20. Replication lag paging

When you evaluate replication lag paging for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

21. Disk growth forecasts

When you evaluate disk growth forecasts for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

22. Package update windows

When you evaluate package update windows for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

23. Node build pipelines

When you evaluate node build pipelines for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

24. Composer audit cadence

When you evaluate composer audit cadence for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.

25. Environment parity checks

When you evaluate environment parity checks for automated response, insist on paired metrics: one symptom and one corroborating dependency signal. Write the rollback in the same ticket as the forward change. If the mitigation touches PHP-FPM, nginx, or the kernel, rehearse it in staging with production-like concurrency — not with synthetic ab alone. Prefer staged worker drains over mass SIGKILL unless you are containing memory corruption class incidents. Document blast radius in plain language for legal and customer comms templates. Revisit thresholds after every major framework upgrade because opcode caches and autoload maps shift latency profiles.