billing help · For platform operators
Server guide
From a bare Ubuntu server to a running installation: Nginx, PHP-FPM, MariaDB, TLS, permissions, the installer, hardening, the scheduler and monitoring.
From a bare Ubuntu server to a running installation
This guide assumes Ubuntu 24.04, a domain pointing at the server (here encrypted.com) and a user with sudo. The layout:
/var/www/encrypted.com/public/ webroot (Nginx root)
/var/www/encrypted.com/app/ PHP source, never served
/var/www/encrypted.com/data/ config, keys, logs, backups, uploads, geo, cache
1. Install the packages#
sudo apt update && sudo apt -y upgrade
sudo add-apt-repository -y ppa:ondrej/php # PHP 8.4 on 24.04 (8.2+ works; the self-check warns below 8.4)
sudo apt install -y nginx mariadb-server \
php8.4-fpm php8.4-cli php8.4-mysql php8.4-curl php8.4-mbstring php8.4-gd php8.4-xml php8.4-intl
sudo timedatectl set-ntp true # providers reject webhooks signed with a wrong clock
sodium, openssl, json and zlib are part of the Ubuntu PHP packages. No Composer and no other PHP or JavaScript library is needed.
2. Secure MariaDB#
sudo mariadb-secure-installation # set a root password, remove anonymous users and the test database
The installer creates the application's database and its three users itself; it only needs the root login once.
3. Copy the files and set permissions#
sudo mkdir -p /var/www/encrypted.com/data
sudo cp -r public app docs /var/www/encrypted.com/
sudo chown -R root:root /var/www/encrypted.com
sudo chown www-data:www-data /var/www/encrypted.com/data # only data/ is writable by PHP
cd /var/www/encrypted.com/public
sudo chown www-data:www-data robots.txt site.webmanifest
sudo touch sitemap.xml llms.txt llms-full.txt && sudo chown www-data:www-data sitemap.xml llms.txt llms-full.txt
The last two lines let the hourly seo.publish job keep the five SEO files current while the rest of the webroot stays read-only.
4. Configure Nginx#
The application needs no rewrite rules, so either vhost from docs/ works:
docs/nginx-hardened.conf— recommended: TLS, clean URLs (try_files … /index.php), long cache for assets, denies dotfiles and helper files.docs/nginx-plain.conf— the minimum; links then look like/admin/?r=settings/users.
sudo cp /var/www/encrypted.com/docs/nginx-hardened.conf /etc/nginx/sites-available/encrypted.com
sudo ln -s /etc/nginx/sites-available/encrypted.com /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
Check the PHP-FPM socket in the file (php8.4-fpm.sock) matches your PHP version.
5. Get a TLS certificate#
sudo apt install -y certbot python3-certbot-nginx
sudo certbot certonly --nginx -d encrypted.com # paths in the hardened vhost match certbot's defaults
sudo nginx -t && sudo systemctl reload nginx
certbot renews the certificate automatically. The system monitor warns when the certificate is close to expiry.
6. Run the installer#
cd /var/www/encrypted.com
sudo -u www-data php app/cli.php install \
--base-url=https://encrypted.com \
--db-name=billing --db-root-user=root --db-root-pass='…' \
[email protected] --super-name='Your Name'
The installer checks PHP, refuses app/ or data/ inside the webroot, creates the database and its three users, generates data/keys/master.key and prints it once, applies the migrations, creates your super-admin account and writes data/config.php last.
A web installer exists too (/install.php), protected by a one-time code that you write to app/install.allow from the shell. Delete public/install.php after installation.
7. Check the installation#
sudo -u www-data php app/cli.php selfcheck # exit code 1 if anything fails
curl -s https://encrypted.com/health # {"status":"ok",…}
Sign in at https://encrypted.com/super/login, then continue with the scheduler and monitoring, email and your first workspace (Workspaces).
Hardening the server
What the application does on its own#
Every response carries its security headers from PHP — a Content-Security-Policy with a per-request nonce and no third-party origins, HSTS over HTTPS, X-Frame-Options, Referrer-Policy, Permissions-Policy, X-Content-Type-Options — so the vhost does not repeat them. Cookies are __Host-, Secure, HttpOnly and SameSite=Lax over HTTPS. Every change requires a CSRF token and a matching origin.
The hardened vhost#
docs/nginx-hardened.conf adds what PHP cannot do itself:
- redirects HTTP to HTTPS, TLS 1.2 and 1.3 only;
- refuses dotfiles,
billing-paths.php,_entry.php, editor backups and the HA node channel; - long, immutable caching for
/assets/; - after installation, uncomment the line that refuses
install.php.
Files#
public/andapp/belong to root and are read-only for PHP; onlydata/belongs towww-data, plus the five SEO files (see Installation).data/config.phpis0640anddata/keys/master.keyis0600. The self-check fails if either is readable by others.- Keep nothing else in
public/: no release zip, no database dump, nophpinfo.php, no.gitfolder. The self-check lists such files and fails. - After copying a release,
php app/cli.php security:manifestconfirms that every file arrived unchanged. - Never run
app/tools/mutate.phpon a server that takes payments. It switches checks off in the source while it runs, and refuses an installed tree unless forced.
Behind a proxy or load balancer#
When requests reach PHP through a proxy (webgate, a CDN, a load balancer), tell the application which addresses are proxies, in data/config.php:
'http' => ['verify_tls' => true, 'trusted_proxies' => ['10.0.0.5', '192.0.2.0/24']],
Without it every visitor appears to come from the proxy's address: sign-in throttling then counts everybody together, and API key IP allowlists compare the wrong address. The self-check, run from the page, warns when it sees a forwarded request from an address that is not listed.
PHP#
In /etc/php/8.4/fpm/php.ini:
expose_php = Off
display_errors = Off
allow_url_include = Off
log_errors = On
upload_max_filesize = 16M ; dispute evidence is capped at 5 MB, logos at 512 KB
post_max_size = 20M
memory_limit = 256M
opcache.enable = 1
The system monitor suggests OPcache and FPM pool sizes for your memory, with the commands to apply them.
The machine#
sudo ufw allow OpenSSH && sudo ufw allow 'Nginx Full' && sudo ufw enable
sudo apt install -y unattended-upgrades && sudo dpkg-reconfigure -plow unattended-upgrades
- SSH with keys only (
PasswordAuthentication no), and no root login. - MariaDB listens on localhost only (the Ubuntu default). On a two-server pair, replication runs over the private link described in Two-server redundancy.
- The system monitor shows whether a reboot is required and whether automatic updates are on.
Scheduler and monitoring
Running the jobs#
Jobs send email, expire checkouts, reconcile bank payments, build analytics, take backups, deliver outbound webhooks and publish the SEO files. Choose one way to run them:
System cron (preferred) — /etc/cron.d/billing:
* * * * * www-data php /var/www/encrypted.com/app/cli.php cron --data=/var/www/encrypted.com/data >/dev/null 2>&1
Then set 'cron' => ['mode' => 'system', …] in data/config.php so page views no longer run jobs.
The cron URL — when you cannot add a cron entry, call https://encrypted.com/cron.php?key=<cron.key from data/config.php> every minute from any scheduler.
Pseudo-cron — with neither, jobs run after page views, at most once a minute. Fine for a quiet test installation, not for production: with no visitors, no email goes out.
Super → Health & jobs shows which one is active, every job's schedule, last result and next run, and Run now.
Uptime monitoring#
Point an external monitor at https://encrypted.com/health (on a plain vhost: /index.php?r=health). It answers 200 with {"status":"ok"} when the database, data directory and scheduler are healthy, and 503 with the reason otherwise. On a two-server pair, /health/write, /health/read and /health/lease tell a load balancer which server can take which traffic.
Logs#
data/logs/— the application log, one JSON object per line. Errors shown to users carry a Reference that appears in the log./var/log/nginx/and the PHP-FPM log — requests and PHP-level errors.- The
logs.prunejob keeps the application logs to a reasonable size.
Alerts you will receive#
Super admins are emailed when: the daily self-check fails, a backup fails or is older than 26 hours, a restore drill fails, the system monitor finds a critical problem, GeoIP files go stale, or a workspace's dispute rate passes the alert level. Each alert is sent at most once a day (system monitor: every 6 hours).