Upgrading
Replacing the release files, applying migrations, version-specific steps, and checking the result.
The routine#
- Take a backup (Super → Backups → Back up now) and download it.
- Unpack the new release next to the old one, then replace
public/andapp/. Never replacedata/: it holds your configuration, keys, uploads and backups. - 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
- Do the version-specific steps below, if any, for every version you skipped.
- 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#
- Replace
public/andapp/(keepdata/). There is no migration and no new setting;php app/cli.php migrateonly refreshes grants. - Confirm the copy:
php app/cli.php security:manifestcompares every file withapp/MANIFEST.sha256and must end with "match the release manifest". Files it lists asEXTRAare PHP files of older versions or of your own; remove what you do not recognise. - 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_proxiesindata/config.php. - No stray files in the webroot: delete the release archive or dumps left under
public/.
- Application code is read-only for PHP:
- Wrapped-blobs installs only (
data/inside the webroot):sudo -u www-data php app/cli.php evidence:wrapre-stores dispute evidence uploaded before 1.0 with the PHP guard. - 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.
- Replace
public/andapp/(keepdata/). New files:public/assets/fonts/(bundled OFL fonts and their licences),public/assets/icons/,public/favicon.ico,public/site.webmanifest, a new defaultpublic/robots.txt, andapp/help-content/,app/fonts/. sudo -u www-data php app/cli.php migrate— migration0011_seo_help(help page edits;pageviews_raw.pagegainshelp).- 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.webmanifestWithout this step everything works; on a plain vhost
/sitemap.xmland/llms.txtare then not served, and the self-check warns (seo_files). - Super → Help & SEO: write the site description, choose the AI-crawler policy, press Publish now.
- Self-check:
seo_filesandhelp_contentshould 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 inrobots.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:granton 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 owndata/backups/.
Older versions: see docs/INSTALL.md in the release package.