Differences

This shows you the differences between two versions of the page.

--- infra:services:wiki [2025/07/26 12:38] – [Admin rights] d404d_idp.hackeriet.no
+++ infra:services:wiki [2026/09/05 16:43] (current) – Add routine DokuWiki upgrade TL;DR atluxity_idp.hackeriet.no
@@ Line 30: / Line 30: @@
 | ''service-dokuwiki-admins'' | ''admin'' |
 | ''hackeriet-styret'' | ''styret'' |
+===== Core upgrades =====
+==== TL;DR: routine upgrade ====
+Review the release notes and plugin compatibility, and arrange a quiet maintenance window with no edits. Then:
+<code bash>
+ssh atluxity@blade.hackeriet.no
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade preflight
+</code>
+If preflight passes, run:
+<code bash>
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade upgrade
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade verify
+</code>
+''upgrade'' downloads the stable release and takes a full backup before changing the installation. Stop on errors. If preflight fails, resolve the reported blockers using the preparation instructions below before continuing.
+Check page rendering and media, Hacker-ID login, a page edit, and its gitbacked backup commit. Plugins and templates require separate maintenance.
+Run maintenance on [[infra:hosts:blade|Blade]] over SSH. The helper is installed as ''/usr/local/sbin/hackeriet-dokuwiki-upgrade'', owned by ''root:root'' with mode ''0755''.
+<code bash>
+ssh atluxity@blade.hackeriet.no
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade preflight
+</code>
+The installation is ''/srv/hackeriet-wiki/dokuwiki''. Backups go to ''/srv/hackeriet-wiki/backups'' and release archives, staging trees and manifests to ''/srv/hackeriet-wiki/upgrade-work''.
+The helper upgrades DokuWiki core. Third-party plugins and templates need separate compatibility review and maintenance. The web Upgrade extension is not the normal upgrade path: core files remain root-owned rather than writable by the web server.
+==== Preparation ====
+Read the target release notes and check PHP, plugin and template compatibility before upgrading. Arrange a maintenance window with no page edits or configuration changes: the helper takes a filesystem backup and copies files into the live installation; it does not suspend requests or provide an atomic deployment.
+Preflight checks required commands, basic write access, installer removal and free space. Its default 1024 MB free-space threshold is only a floor; allow space for the complete backup, downloaded release and extracted staging tree.
+If preflight reports a writable installation root or remaining ''install.php'', back up before normalizing permissions:
+<code bash>
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade backup
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade secure-baseline
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade audit-permissions
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade preflight
+</code>
+''secure-baseline'' removes ''install.php'' and changes ownership and modes. It makes core directories root-owned, retains web write access to ''data/'' and ''conf/'', and makes ''conf/local.php'' web-owned. It also normalizes files under ''data/'' recursively, including any backup-plugin metadata. Check gitbacked operation after applying it. Web installation of plugins/templates may require separate SSH maintenance with this ownership model.
+==== Upgrade ====
+<code bash>
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade upgrade
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade verify
+</code>
+''upgrade'' downloads the stable release from ''https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz'', prints the current and staged versions and the archive SHA256, and stops if the versions match. It creates a full filesystem backup before copying core files, preserves ''conf/'' and ''data/'' during the copy, removes release-listed obsolete files and ''install.php'', reapplies permissions, reloads active nginx, and runs the permission audit. It prints backup and manifest paths. An error after copying begins may leave a partially upgraded installation; retain the command output and backup path.
+For a selected release, use a previously downloaded archive and an independently obtained trusted checksum:
+<code bash>
+sudo /usr/local/sbin/hackeriet-dokuwiki-upgrade upgrade --tarball /root/dokuwiki-release.tgz --sha256 EXPECTED_SHA256
+</code>
+Without ''--sha256'', the hash is reported but not compared against an expected value. ''--force'' reinstalls a matching version. Run ''--help'' for other options. The current ''upgrade --dry-run'' cannot complete download/staging simulation and is not a release preview.
+==== Verification ====
+''audit-permissions'' checks the installation root, selected core directories, world-writable paths, web write access to ''conf/'' and ''data/'', and absence of ''install.php''. It is a baseline audit, not an exhaustive ACL, symlink or individual-file access check.
+Run ''verify'' with sudo to include this audit followed by local and public HTTP checks. A failed permission audit stops verification before HTTP checks. The local check follows redirects, so a successful result alone does not establish that the local PHP backend served the page.
+After maintenance, check page rendering and media, Hacker-ID login, a page edit, and a corresponding gitbacked backup commit. Check configuration saving if permissions were changed. HTTP success alone does not verify these functions.
+==== Recovery ====
+Use the full backup printed by the helper, not just the content repository. Keep writes suspended during recovery. Verify the backup checksum with ''sha256sum -c'' from the backup directory and inspect it with ''tar -tzf'' before restoring.
+Move the failed installation aside and extract the backup into ''/srv/hackeriet-wiki'' as root, preserving numeric ownership, ACLs and extended attributes (''tar --numeric-owner --acls --xattrs -xzpf BACKUP -C /srv/hackeriet-wiki''). Restoring over the failed tree leaves newly introduced files behind; the short rollback command printed by the helper does not remove them. A full restore also rolls back content to backup time, so preserve any subsequent edits first.
+The backup uses ''--one-file-system'' and does not include data on nested mounts or external symlink targets. Confirm these are covered separately if the installation uses them. After restoration, review the restored permission baseline, reload the relevant web/PHP services, and repeat functional verification. Retain the failed tree until recovery is confirmed.
+==== References ====
+  * [[https://www.dokuwiki.org/install:upgrade|DokuWiki upgrade instructions]]
+  * [[https://www.dokuwiki.org/plugin:upgrade|DokuWiki Upgrade extension]]