billingHelp

Upgrading

Replacing the release files, applying migrations, version-specific steps, and checking the result.

The routine#

  1. Take a backup (Super → Backups → Back up now) and download it.
  2. Unpack the new release next to the old one, then replace public/ and app/. Never replace data/: it holds your configuration, keys, uploads and backups.
  3. Apply migrations and refresh the grants:
cd /var/www/encrypted.com
sudo -u www-data php app/cli.php migrate --db-root-user=root   # asks for the root password; or run as the migrate user
  1. Do the version-specific steps below, if any, for every version you skipped.
  2. Run the self-check, open the Platform overview, and make one test payment in a test workspace.

On a two-server pair, upgrade the replica first, then the primary; the cluster page shows both versions.

Version-specific steps#

  1. Replace public/ and app/ (keep data/). There is no migration and no new setting; php app/cli.php migrate only refreshes grants.
  2. Confirm the copy: php app/cli.php security:manifest compares every file with app/MANIFEST.sha256 and must end with "match the release manifest". Files it lists as EXTRA are PHP files of older versions or of your own; remove what you do not recognise.
  3. Run the self-check from Super → Self-check (not only from the command line: the PHP-FPM settings and the proxy check are read from the web request). New items are listed in the help under Health, jobs, self-check. Typical first-run findings:
    • Application code is read-only for PHP: sudo chown -R root:root app public, then step 3 of §9i again for the five SEO files.
    • Client addresses are read correctly: behind webgate or another proxy, add its address to http.trusted_proxies in data/config.php.
    • No stray files in the webroot: delete the release archive or dumps left under public/.
  4. Wrapped-blobs installs only (data/ inside the webroot): sudo -u www-data php app/cli.php evidence:wrap re-stores dispute evidence uploaded before 1.0 with the PHP guard.
  5. Behaviour that changes, so support knows:
    • The "confirm your email" link now needs the customer to be signed in. Links already sent keep working, after sign-in.
    • A customer account whose address was never confirmed loses its password when a payment for that address arrives without sign-in, when staff grant access or record an offline payment for it, or when an API key creates a checkout for it. The customer sets a new password through the emailed link. Confirmed accounts are unaffected.
    • A provider event signed by a credential set of another provider, or of the other mode (test / live), no longer acts on a payment; it is answered 200 and logged as webhook.source_mismatch. If a product was moved from a test set to a live set of a different provider account while test payments were still open, those test payments now stay as they are.
    • Receipt lookups that open nothing answer 429 after 30 tries in 10 minutes from one address; five wrong "current password" entries close the change-password form for 15 minutes.
  1. Replace public/ and app/ (keep data/). New files: public/assets/fonts/ (bundled OFL fonts and their licences), public/assets/icons/, public/favicon.ico, public/site.webmanifest, a new default public/robots.txt, and app/help-content/, app/fonts/.
  2. sudo -u www-data php app/cli.php migrate — migration 0011_seo_help (help page edits; pageviews_raw.page gains help).
  3. Let PHP keep the SEO files current while the webroot stays root-owned (once):
    cd /var/www/encrypted.com/public
    sudo touch sitemap.xml llms.txt llms-full.txt
    sudo chown www-data:www-data robots.txt sitemap.xml llms.txt llms-full.txt site.webmanifest

    Without this step everything works; on a plain vhost /sitemap.xml and /llms.txt are then not served, and the self-check warns (seo_files).

  4. Super → Help & SEO: write the site description, choose the AI-crawler policy, press Publish now.
  5. Self-check: seo_files and help_content should pass. Nginx needs no change.
sudo cp -r app public /var/www/encrypted.com/          # keep data/ untouched
sudo -u www-data php /var/www/encrypted.com/app/cli.php migrate   # applies 0010_api_backups + refreshes grants
sudo php /var/www/encrypted.com/app/cli.php backup:grant --db-root-user=root   # once: the restore drill's scratch database
sudo -u www-data php /var/www/encrypted.com/app/cli.php backup:run             # first backup now (otherwise tonight at 02:37 UTC)
  • Backups go to data/backups/ nightly. The restore drill runs on Sundays, and GFS keeps 7 daily, 4 weekly and 12 monthly archives. Copy archives off the server (Super → Backups → Download, or scp), and keep the master key (data/keys/master.key) in yet another place. The self-check warns until an off-box copy is recorded. Details: BACKUPS.md.
  • Disk: an archive is roughly the size of the database plus uploads, GeoIP files and downloads. A run refuses to start below twice that much free space.
  • API v1 and webhooks: Workspace → Settings → API & webhooks. Reference at /api/docs, OpenAPI at /api/v1/openapi.json. Details: API.md. Nothing changes for existing pages. /api/ is already disallowed in robots.txt.
  • Plain vhost (no rewrites): API URLs are /api/?r=v1/…. PATCH/DELETE have POST aliases, and also work against /api/index.php?r=v1/….
  • A pair: upgrade as in §9f. Run backup:grant on each node (--admin-host= if the node admin account is not @localhost). Backups and webhook deliveries run on the writable node, and each node keeps its own data/backups/.

Older versions: see docs/INSTALL.md in the release package.