Upgrades

DesertCMS upgrades are staged from Admin Settings > Upgrade DesertCMS.

Upload the newest desertcms-openbsd-runtime-YYYY-MM-DD.tar.gz release archive, then click Stage and queue upgrade. Source archives also work when they contain the full CMS app files, installer, tools, SQL, docs, and default theme. The admin app validates that the archive looks like a DesertCMS release, saves it under the site's private data directory, and writes an upgrade job.

The upload box shows the selected archive name and size before submission. Refreshing the settings page after a successful queue does not create another job for the same archive. If the same SHA-256 release is already queued, running, or done, the admin page shows the existing job instead of adding a duplicate.

A root-owned worker applies queued upgrades once per minute. It:

• backs up the current application tree to /var/backups/desertcms-app-*.tar.gz
• extracts and validates the staged release archive
• replaces the root-owned application files under /usr/local/www/desertcms
• keeps site data, originals, backups, configs, and generated public files outside the app tree
• runs database migrations and public rebuilds for /etc/desertcms.conf and contributor configs
• restarts desertcms_slowcgi and reloads httpd after httpd -n passes

New installs add the worker automatically. Existing installs can install it with:

doas perl /usr/local/www/desertcms/tools/openbsd-apply-upgrade.pl --install-cron

The admin request does not overwrite application files directly. This keeps the _desertcms web user from having write access to the application code while still giving admins a simple drag-and-drop release workflow.

Job Status

Recent jobs are shown on the Upgrade settings page:

• queued: the archive was staged and is waiting for the root worker.
• running: the root worker is applying the release.
• done: the release was applied successfully.
• failed: the worker could not apply the release; the message column contains the failure text.

If an upgrade fails, fix the issue, upload the corrected release archive, and queue a new upgrade. The previous app backup remains in /var/backups.

Troubleshooting

If staging fails with a message like:

cannot write /var/desertcms/upgrades/jobs/...: Permission denied

repair ownership of the private upgrade directory:

doas install -d -o _desertcms -g _desertcms -m 750 /var/desertcms/upgrades /var/desertcms/upgrades/jobs
doas chown -R _desertcms:_desertcms /var/desertcms/upgrades
doas chmod 750 /var/desertcms/upgrades /var/desertcms/upgrades/jobs

For contributor deployments, repeat the same ownership repair for the relevant /var/desertcms-sites/<site>/upgrades directory. Current workers also repair job-file ownership after root writes status updates, but the directory itself must be writable by the CMS service user for admin staging.

If a job stays queued, confirm root's crontab has the worker:

doas crontab -l | grep openbsd-apply-upgrade

Then run one worker pass manually to see the error:

doas perl /usr/local/www/desertcms/tools/openbsd-apply-upgrade.pl