HisarBlok · documentation

Updates and backups

How a new release is applied, what happens when something goes wrong, what a backup holds, and how a site moves to another server.

All docs

For version 0.13.1.

Signed updates

A release is three files side by side: the code package (hisarblok-X.Y.Z.tar.gz), a manifest listing the SHA-256 of every file in the package, and an Ed25519 signature over that manifest. Updating is one command on the server, run as the account that owns the code and data/config.php (on HestiaCP, the site's user). Running it as root is refused.

sudo -u SITEUSER php …/tools/update.php hisarblok-X.Y.Z.tar.gz

In order:

The signature is checked against the public keys shipped with the installation before the manifest is even parsed. Another key, a revoked key, a missing signature, one changed byte, a path that would write outside the code, or a downgrade is refused.
A backup comes first; the new code is unpacked into a separate directory and every file is checked against its own hash.
The admin says "being updated" for a moment; the sites stay up. The code is switched in one move, by renaming.
Database migrations run and every site is rebuilt by the new code.
If any of these steps fails, both the code and the database go back as they were, by themselves.

--undo takes the last update back, --recover finishes an interrupted run, --dry-run only verifies, and --verify compares the code on disk with the installed release's hashes. The admin never writes code. System → Updates shows the installed version and the trusted keys; with update_url set in the configuration it also checks whether a newer signed release exists. That check is off by default: HisarBlok makes no outside connections on its own.

Updating by hand

Take a backup, unpack the new release over the old one, and rebuild the site. A release package carries no data/, so an update cannot overwrite content or configuration. Database changes apply themselves on the first request after the update.

sudo -u www-data php tools/backup.php --label=before-update
# replace the code with the new release, then:
sudo chown -R www-data: data && sudo chmod 750 data
sudo -u www-data php tools/rebuild.php example.com

Backups

A backup is a single .tar.gz holding everything that cannot be regenerated: a consistent copy of the database taken while the site runs, the configuration, module data, each site's uploaded media, and a manifest with the SHA-256 of every file. Built pages are not included; they are rebuilt from the database. The format is the same on MySQL/MariaDB installations, so every backup restores onto either database.

sudo -u www-data php tools/backup.php                 # back up now
sudo -u www-data php tools/backup.php --list          # what is stored
sudo -u www-data php tools/backup.php --verify=NAME   # read one through, check every checksum

Backups go to data/backups/, never inside a document root. The newest 14 are kept; the number and the directory can be changed in the configuration. In the admin, System → Backups lists them, makes one on demand and offers downloads; a download asks for your password again.

Copy your backups off the server. A backup on the same disk does not survive the disk.

Restoring

Restoring replaces the database the admin runs on, so it is done on the server with tools/restore.php, not in the admin, and can be tried first with --dry-run. In order: every checksum and every file name in the archive is checked (a name that would write outside its place is refused); a backup from a newer HisarBlok is refused; the current state is backed up; the database's integrity is checked; only then are the database, configuration, data and media swapped in, and the restore is recorded in the audit log. Then each site is rebuilt.

Moving to another server works the same way: install HisarBlok there, copy the backup into data/backups/, restore it, rebuild the sites and move DNS.

Export

Apart from backups, a site's whole content can be taken out with System → Backups → Export a site or tools/export.php, as one .zip in an open, documented format: plain JSON Lines files, the original images and a SHA-256 manifest. Passwords, two-factor secrets, sessions and mail settings are never in it; members and form answers only when asked for. The same file reads into another HisarBlok installation with tools/import.php hisarblok.

The command line: bin/hisarblok

Every server-side job is a script in tools/; bin/hisarblok is one door to all of them:

sudo -u www-data bin/hisarblok help                    # every command and what it does
sudo -u www-data bin/hisarblok rebuild example.com     # regenerate a site
sudo -u www-data bin/hisarblok doctor                  # the installation's health

doctor checks the admin's site health rows plus the scheduled job, the build queues and the update keys; --json connects it to monitoring. Each command runs the tool as a process of its own, with no shell seeing the arguments, behind the tool's own ownership check.