Operations, Upgrades & Performance

Four goals after launch: backups, upgrades, rollback, observability. Examples use /www/wwwroot/yecha.org; replace it with your path.

On this page

Backup

B=/root/backup/$(date -u +%Y%m%dT%H%M%SZ); mkdir -p "$B"
mysqldump -h127.0.0.1 -uyecha -p --single-transaction --routines --default-character-set=utf8mb4 yecha \
  | gzip > "$B/yecha.sql.gz"
tar czf "$B/site.tar.gz" -C /www/wwwroot yecha.org \
  --exclude='var/cache/*' --exclude='var/log/*'
cp -a /www/wwwroot/yecha.org/config.inc.php "$B/config.inc.php.orig"
ls -lh "$B"
  • Keep all three: database, site files and config.inc.php. uploads/ is inside the site archive.
  • Store backups outside docroot; rehearse a restore on an idle machine periodically.
  • Tools → Backup creates a full DB backup; Upgrade does one automatically.
  • Before deleting content, export ye_contents, ye_relationships, ye_metas, ye_poly_contents separately for precise recovery.

Upgrade

  1. Back up (above) and record the current YC_VERSION.
  2. Replace core files: index.php, core/, admin/, lang/; keep config.inc.php, uploads/, var/.
  3. Add/replace themes and plugins; back up same-named themes first.
  4. Migrations are idempotent (Upgrade::apply() and plugin migrations/); preview with CLI:
php tools/upgrade.php --component core --dry-run
php tools/upgrade.php --component core
  1. Flush caches and rebuild the baked home page (caches).
  2. Self-check: 10 sampled pages return 200, zero 5xx; admin login and settings save; theme/plugin counts match directories; /sitemap.xml, /feed work; one /en/ page checked.

Rollback

B=/root/backup/<timestamp>
gunzip -c "$B/yecha.sql.gz" | mysql -h127.0.0.1 -uyecha -p yecha
tar xzf "$B/site.tar.gz" -C /www/wwwroot
cp -a "$B/config.inc.php.orig" /www/wwwroot/yecha.org/config.inc.php
php -r 'chdir("/www/wwwroot/yecha.org"); require "config.inc.php"; require "core/bootstrap.php"; Cache::flush("pages"); Cache::flush("blocks");'

Restoring the database overwrites content created after the backup — export that new content first.

Caches

LocationPurposeFlush when
var/cache/pagesFull-page cachecontent, theme, menu changes
var/cache/blocksSidebar/block cachesidebar or plugin changes
var/home-static/Baked home pages (incl. /en/)home, theme, analytics changes
php -r 'chdir("/www/wwwroot/yecha.org"); require "config.inc.php"; require "core/bootstrap.php"; Cache::flush("pages"); Cache::flush("blocks");'
rm -f /www/wwwroot/yecha.org/var/home-static/index.html \
      /www/wwwroot/yecha.org/var/home-static/en/index.html
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: example.com' http://127.0.0.1/

/changelog sends Cache-Control: no-cache so it is always fresh; for other pages keep any upstream HTML cache rules consistent with the origin's Cache-Control.

Cron

JobFrequencyPurpose
php tools/sync-views.phpdailyFold ye_views details into ye_contents.views and clear details
Backup scriptdailyDB + files, stored off-site
Rebuild baked homeafter content changesor let the home-static plugin handle it
Health probeevery 5 min/healthz
30 3 * * * cd /www/wwwroot/yecha.org && php tools/sync-views.php >> var/log/cron.log 2>&1
0 4 * * * /root/bin/yecha-backup.sh >> /var/log/yecha-backup.log 2>&1

Performance

Follow instrument → measure → isolate → fix → re-measure. Built-in optimisations:

AreaMechanism
Home counterFront::postsTotal() reads ye_options.stats.posts_total (O(1)) → cache (3600s) → live COUNT fallback; since 1.2.0 home() no longer runs COUNT(*) on every request
Term countsPrecomputed ye_metas.count; the SELECT COUNT(*) subqueries were removed from bundled themes in 1.2.0
Deep paginationye_meta_page_bounds keyset fast path keeps very large offsets in milliseconds; tw joined in 1.2.4 with a safe fallback
IndexesOrdered covering indexes like (type,status,deleted_at,published_at,id); EXPLAIN before changing ORDER BY
CacheHit rate and cache-before-compute ordering are the first things to check

Checklist (look at the origin and the page): PHP rendering and SQL, PHP-FPM processes/concurrency, OPcache hits, cache hits, asset size and compression, image dimensions and lazy loading, TLS handshake and certificate chain, DNS TTL, third-party external links.

mysqldumpslow -s t /var/log/mysql/slow.log | head -20
curl -s -o /dev/null -w 'code=%{http_code} total=%{time_total}s\n' -H 'Host: example.com' http://127.0.0.1/
php -l core/Front.php

Monitoring

  • /healthz for liveness; probe home, a content page, admin, /sitemap.xml, /feed.
  • Watch 5xx rate, P95 latency, active PHP-FPM processes, slow-query count, disk (cache/log/uploads) and backup success.
  • After each release run the upgrade self-check; roll back first, diagnose offline afterwards.

Troubleshooting

SymptomOrder of checks
Blank home / template missingtheme layout.php → var/log/php-error.log → switch back to yecha
Front end unchanged after an editpage cache / block cache / baked home file
Admin login loopsHTTPS detection, site hostname, cookies
500 when savingenable DEBUG briefly, php -l, missing columns after migrations
List page suddenly slowEXPLAIN for filesort regressions; check counters didn't become live subqueries
Upload failsuploads/ ownership and disk space
Multilingual page shows Chinesetranslation status / prefix / term aliases (i18n)
Changelog not updating/changelog is a DB content page; editing CHANGELOG.md alone does nothing (release)

Release standard

RELEASE.md is the single standard — five mandatory steps:

  1. Changelog check: write both root CHANGELOG.md and the live /changelog content page (with its English translation), six elements each (root cause / fix / criteria / verification / deploy / rollback).
  2. Feature completeness: php -l, diff matches the changelog, changes present in the package (compare content SHA after decompressing — gzip header timestamps make .tar.gz SHAs non-deterministic).
  3. Package: git archive v<version> with a top-level yecha-<version>/ directory.
  4. GitHub: tag + Release + tar asset; use tokens only in command URLs, never in git config.
  5. Close-out: origin and public sampling, flush page cache, update the home version badge, commit to git.

Version lives in core/version.php; release headings must stay ## YYYY-MM-DD · YeCha <version> · <title> because the home "Latest updates" block parses that format.