====== Wiki ======



===== Intro =====


This Wiki is running [[https://dokuwiki.org|Dokuwiki]] and is hosted on Blade.

===== Backup =====


The contents of the wiki is backed up automagically to the [[https://github.com/hackeriet/wiki/tree/main/meta|hackeriet/wiki Github repo]], using the [[https://github.com/woolfg/dokuwiki-plugin-gitbacked|gitbackend]] plugin. The wiki and repo could contain personal information, and the repo is therefore private with limited access granted across Hackeriet.

===== Login =====

New users can use Hacker-ID to log in without sharing PII. When this option is used, the changelog will only contain your Hacker-ID user account and UUID.

You can also use Github as login method to get edit permissions to the Wiki. This makes changelogs retain your Github sign-in email address and real name.

==== Admin rights ====
The login to the main admin user is in hackerpass, and members can use that login to grant themselves more permissions as need be.

Hacker-ID users can get admin rights assigned automatically by being members of the ''service-dokuwiki-admins'' group. Note that DokuWiki does not unassign groups from removed members; it only adds the group to users that are currently members.

DokuWiki's way of handling groups means that every single IDP group gets assigned to the person on login, even those not relevant for DokuWiki. To combat this, DokuWiki instead reads a custom claim ''dokuwiki_groups'' from Hacker-ID which contains the following values:

^ IDP group ^ Claim value ^
| ''service-dokuwiki-users'' | ''user'' |
| ''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]]