Skip to content

Scaling to high traffic ​

One server with the default settings handles small and medium sites well. When recordings arrive by the thousands every minute, or when you run the SaaS edition, move the state off the server (Redis and an S3 bucket), give recordings their own queue and workers, and add servers behind a load balancer. php artisan replora:doctor tells you what is still missing.

20 minutesDevOpsServer administrationSingle user · SaaS

How ingest scales ​

The tracking script sends a small gzipped batch every few seconds per visitor (about 12 requests a minute). The ingest endpoint /i/<key> only checks the batch and puts it on the queue, so web servers stay fast; the work happens in the queue workers. Scaling therefore means:

  1. Enough PHP-FPM processes on the web servers to accept the requests.
  2. A fast queue (Redis) and enough workers for the batches, ideally on their own queue.
  3. Shared state (sessions, cache, rate limits, recordings) so any server can answer any request.

Check with replora:doctor ​

bash
php artisan replora:doctor                  # for several servers behind a load balancer
php artisan replora:doctor --single-server  # for one server: per-server state is only a warning

Each finding starts with ✘ (must be fixed: the command exits with code 1, so a deploy pipeline can stop on it) or ! (advice). With nothing to report it prints ✔ Ready to scale: no per-server state, queued ingest, shared real-time. It always ends with the worker commands for your settings, for example Workers: php artisan queue:work --queue=ingest (recording batches) and php artisan queue:work (everything else).

FindingLevelFix
SESSION_DRIVER=file keeps dashboard sessions on one server: use redis (or database).✘ (! with --single-server)SESSION_DRIVER=redis
CACHE_STORE=file keeps rate limits, locks and the ingest cache on one server: use redis.✘ (! with --single-server)CACHE_STORE=redis
RECORDINGS_DRIVER=local stores recordings on one server: use s3 (AWS S3, Cloudflare R2, MinIO).✘ (! with --single-server)Recording storage
QUEUE_CONNECTION=sync processes every recording batch inside the ingest request…!QUEUE_CONNECTION=redis and workers
RECORDINGS_INGEST_QUEUE=default: recording batches share a queue with e-mail, alerts and AI jobs…!RECORDINGS_INGEST_QUEUE=ingest and workers for both queues
QUEUE_CONNECTION=database works, but redis handles high ingest volume much better.!QUEUE_CONNECTION=redis
REPLORA_REALTIME=websocket but broadcasting is not set up…!Set BROADCAST_CONNECTION=reverb and the REVERB_* keys, or go back to polling
REVERB_SCALING_ENABLED=false: with more than one Reverb server, enable it…! (not with --single-server)REVERB_SCALING_ENABLED=true
APP_DEBUG=true in production shows internal details to visitors.✘APP_DEBUG=false
REPLORA_MODE=saas but the saas/ folder is missing: running as Single user.!Upload the SaaS package, or set REPLORA_MODE=single
Module … was not loaded: …!The reason says why (for example a module made for another version)
ini
# .env on every server
SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis
RECORDINGS_INGEST_QUEUE=ingest

REDIS_CLIENT=phpredis
REDIS_HOST=10.0.0.5
REDIS_PORT=6379
REDIS_PASSWORD=a-long-password

RECORDINGS_DRIVER=s3
RECORDINGS_BUCKET=replora-recordings
RECORDINGS_REGION=auto
RECORDINGS_ENDPOINT=https://ACCOUNT_ID.r2.cloudflarestorage.com
RECORDINGS_KEY=…
RECORDINGS_SECRET=…

Install Redis (sudo apt install -y redis-server) and PHP's Redis extension (php8.3-redis) first. After changing .env: php artisan config:clear and php artisan queue:restart. Redis is also what keeps scheduled tasks on one server and makes locks (one update at a time) work across servers.

Workers ​

With RECORDINGS_INGEST_QUEUE=ingest, run two pools (Supervisor examples in Background worker):

bash
php artisan queue:work --queue=ingest --sleep=1 --tries=3 --max-time=3600   # many: recording batches
php artisan queue:work --sleep=3 --tries=3 --max-time=3600                  # one or two: alerts, emails, stylesheets
  • Start with as many ingest workers as the server has CPU cores and add more when jobs wait.
  • Workers can run on separate machines: they need the same files, the same .env, Redis, the database and the bucket.
  • Watch the queues with php artisan queue:monitor redis:ingest,redis:default --max=1000, and the Background jobs check on the System page.

Several web servers ​

  1. Put a load balancer in front (Nginx, HAProxy, a cloud load balancer). Sticky sessions are not needed once sessions are in Redis.
  2. Every server gets the same application files and the same .env (the same APP_KEY!).
  3. Shared: PostgreSQL, Redis, the recordings bucket.
  4. Run cron on every server or on one: module tasks run on one server only, thanks to the shared cache. The service check and update check (replora:health, replora:update --check) run wherever cron runs, so one cron server is simplest.
  5. Updates: install them on one server (php artisan replora:update) and deploy the same files to the others, or upload the release to all of them and run php artisan replora:upgrade once.
  6. Behind the load balancer, restore visitors' real addresses with Nginx's real_ip module (see VPS).

Web server and PHP-FPM ​

  • Raise pm.max_children in /etc/php/8.3/fpm/pool.d/www.conf to what memory allows (each PHP process needs roughly 40–80 MB): for example pm = dynamic, pm.max_children = 50, pm.start_servers = 10, pm.min_spare_servers = 5, pm.max_spare_servers = 20.
  • Keep OPcache on (the default with PHP-FPM).
  • RECORDINGS_INGEST_PER_MINUTE (default 600) limits tracker requests per minute from one IP address. Raise it when many visitors share one address (offices, mobile networks, schools).

Database ​

  • PostgreSQL on its own machine (or a managed service) for large installations. Set DB_HOST on every server.
  • Give it memory: shared_buffers about 25 % of RAM, effective_cache_size about 50–75 %.
  • Shorter retention means fewer rows: recordings, their pages and their report rows are deleted every night once expired.
  • Many web servers and workers open many connections: put PgBouncer in front if you reach max_connections.

Live updates (WebSockets) ​

The dashboard refreshes live visitors and lists by polling (REPLORA_REALTIME=polling, every REPLORA_POLL_SECONDS, default 5). With many dashboard users, push updates over WebSockets with Laravel Reverb instead:

ini
REPLORA_REALTIME=websocket
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=replora
REVERB_APP_KEY=a-random-key
REVERB_APP_SECRET=a-random-secret
REVERB_HOST=analytics.example.com
REVERB_PORT=443
REVERB_SCHEME=https
REVERB_SCALING_ENABLED=false     # true with more than one Reverb server (shares connections through Redis)

Run the server (it listens on 0.0.0.0:8080; change with REVERB_SERVER_HOST / REVERB_SERVER_PORT) under Supervisor:

ini
[program:replora-reverb]
command=php /var/www/replora/artisan reverb:start
user=www-data
autostart=true
autorestart=true
stopwaitsecs=30

and pass WebSocket connections through Nginx, inside the site's server block:

nginx
location ~ ^/(app|apps)/ {
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://127.0.0.1:8080;
}

Clients learn which transport to use from the API (GET /api/v1/app); polling endpoints keep working either way.

Replora: see what your visitors see.