Skip to content

Install on a VPS ​

On a server with SSH access, Replora installs with one command. This guide uses Ubuntu 24.04 with Nginx, PHP-FPM 8.3 and PostgreSQL 16, then adds HTTPS, the background worker and cron. Debian and other distributions work the same way with their own package names.

20–30 minutesDevOps, site ownersServer administrationSingle user · SaaS

Replace analytics.example.com with your domain, /var/www/replora with the folder you choose and 1.0.0 with your version. Point the domain's DNS A (and AAAA) record at the server first.

Install the server packages ​

Ubuntu 24.04 ships PHP 8.3 and PostgreSQL 16:

bash
sudo apt update
sudo apt install -y nginx postgresql unzip supervisor \
  php8.3-fpm php8.3-cli php8.3-pgsql php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-intl
sudo systemctl enable --now nginx postgresql php8.3-fpm

sodium, fileinfo, ctype, tokenizer, openssl and zlib are part of PHP's base package on Ubuntu. On Ubuntu 22.04 or Debian, add PHP 8.3 from the Ondřej Surý repository first (sudo add-apt-repository -y ppa:ondrej/php).

For busy sites also install Redis now: sudo apt install -y redis-server php8.3-redis (see Scaling).

Raise the upload limits in /etc/php/8.3/fpm/php.ini (the largest upload is a 20 MB document on a SaaS website page), then reload PHP:

ini
upload_max_filesize = 20M
post_max_size = 25M
bash
sudo systemctl reload php8.3-fpm

Create the database ​

bash
sudo -u postgres psql -c "CREATE USER replora WITH PASSWORD 'a-long-password';"
sudo -u postgres psql -c "CREATE DATABASE replora OWNER replora ENCODING 'UTF8';"

The user owns the database, so it can create the tables. Keep the password for the next step.

Unpack the files ​

bash
sudo mkdir -p /var/www && cd /var/www
sudo unzip -q ~/replora-single-1.0.0.zip
sudo mv replora-single-1.0.0 replora
sudo chown -R www-data:www-data replora

Run the installer ​

bash
cd /var/www/replora
sudo -u www-data php artisan replora:install \
  --url=https://analytics.example.com \
  --purchase-code=YOUR-PURCHASE-CODE \
  --db-host=127.0.0.1 --db-port=5432 --db-database=replora --db-username=replora --db-password='a-long-password' \
  --admin-name="Alex Morgan" [email protected] --admin-password='another-long-password'

The command checks the server, verifies the purchase code and downloads the modules, writes .env, creates the tables and the first administrator. Leave any option out to be asked for it. With the SaaS package add --mode=saas (or answer the question). Every option is explained in Command-line install.

Run it as the web server user (www-data), so every file it creates belongs to that user.

The web installer works too

Prefer the browser? Skip this step, finish the Nginx and HTTPS steps below, and open https://analytics.example.com: the web installer asks the same questions.

Configure Nginx ​

Create /etc/nginx/sites-available/replora:

nginx
server {
    listen 80;
    listen [::]:80;
    server_name analytics.example.com;

    root /var/www/replora/public;
    index index.php;
    charset utf-8;

    # Uploads (website page documents up to 20 MB) and recording batches (up to 5 MB compressed).
    client_max_body_size 25m;

    # Compress text answers: the dashboard, the API's JSON and the tracking script t.js.
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_vary on;
    gzip_types text/plain text/css application/javascript application/json image/svg+xml;

    # Everything that isn't a file in public/ goes to Laravel. This includes the tracker endpoints
    # /t.js, /c/<key>, /i/<key>, /s/<key>, /x/<key> and /css/<sha>.css: they are routes, not files.
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # The built dashboard: file names carry a hash, so they can be cached for a year.
    location ^~ /build/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
        try_files $uri =404;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_hide_header X-Powered-By;
        fastcgi_read_timeout 300;   # one-click updates and AI answers can take a while
    }

    # No other PHP file is ever run, and hidden files (.env, .git…) are never served.
    location ~ \.php$ { return 404; }
    location ~ /\.(?!well-known) { deny all; }
}
bash
sudo ln -s /etc/nginx/sites-available/replora /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Don't add a catch-all rule for .js or .css files

A rule such as location ~* \.(js|css)$ { try_files $uri =404; } would answer 404 for /t.js and /css/<sha>.css, which are produced by Replora, not stored in public/: recordings stop and replays lose their styles. Cache only /build/, as above.

CORS is handled by Replora

Your websites call /t.js, /c/…, /i/…, /s/… and /x/… from other domains. Replora sends the right Access-Control-Allow-Origin headers itself, including the answer to the browser's OPTIONS preflight. Don't add CORS headers in Nginx: duplicated headers make browsers reject the answer. Which websites may send recordings is set per website (allowed domains) in the dashboard.

Turn on HTTPS ​

bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d analytics.example.com --redirect

Certbot gets a free Let's Encrypt certificate, adds the listen 443 ssl lines and the redirect from http to https, and renews the certificate automatically (systemctl list-timers | grep certbot shows the timer). The SSL certificate check on the System page warns 14 days before it expires.

If you installed with an http:// address, change APP_URL in .env to the https:// address and SANCTUM_STATEFUL_DOMAINS to the bare host (analytics.example.com), then run sudo -u www-data php artisan config:clear.

Start the background worker ​

Recordings are processed by php artisan queue:work. Keep it running with Supervisor:

ini
; /etc/supervisor/conf.d/replora-worker.conf
[program:replora-worker]
command=php /var/www/replora/artisan queue:work --sleep=1 --tries=3 --max-time=3600
user=www-data
numprocs=2
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stopwaitsecs=60
stdout_logfile=/var/www/replora/storage/logs/worker.log
bash
sudo supervisorctl reread && sudo supervisorctl update
sudo supervisorctl status

systemd instead of Supervisor, separate queues for recording batches and Redis are covered in Background worker & email.

Add the cron line ​

bash
echo "* * * * * cd /var/www/replora && php artisan schedule:run >> /dev/null 2>&1" | sudo crontab -u www-data -

This replaces www-data's crontab; if it already has entries, add the line with sudo crontab -u www-data -e instead. What it runs: Scheduler (cron).

Check the installation ​

bash
cd /var/www/replora
sudo -u www-data php artisan replora:doctor --single-server
sudo -u www-data php artisan replora:health

replora:doctor checks the configuration for production (lines with ✘ must be fixed; ! are advice). replora:health runs the service checks that the System page shows: database, cache, background jobs, scheduled tasks, storage, email, website, tracking script, SSL certificate, license and modules. Sign in at https://analytics.example.com/login and open Administration › System to see them.

Behind Cloudflare or a load balancer ​

Replora sees the address that connects to PHP. Behind a proxy that is the proxy's address, so excluded-IP rules and location look-ups would see the proxy instead of the visitor. Restore the real address in Nginx with the real_ip module, for example for Cloudflare:

nginx
# in the server block, one set_real_ip_from line per Cloudflare range (https://www.cloudflare.com/ips/)
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 2400:cb00::/32;
real_ip_header CF-Connecting-IP;

Cloudflare's CF-IPCountry header can also give visitors' countries without a location database: switch on Proxy headers in the Visitor location card of the dashboard's settings (administrators).

Replora: see what your visitors see.