Software Updates and Recovery

Updated: 2026-10-22. Current stable release: v1.0.3; full, advanced and guided upgrade packages are available from https://yourkitchenlibrary.com/download/. The website's stable catalog must agree with the downloadable packages and their SHA-256 checksums.

What the Owner sees

From the account menu, enable Admin View and open Software Updates. Only the actual active Owner account can check for or approve upgrades; a normal Admin or another role cannot perform software maintenance.

The updater displays the installed and latest stable versions, along with the last check and current stage. Click Check for Updates to refresh the status. When a newer release is available, read the release notes and type UPDATE to confirm. Installation is never triggered automatically simply because a new release exists.

Your browser may temporarily disconnect when the web container is recreated. Afterward, reopen the page and confirm the installed version and health.

Synology first-upgrade safeguards

The first outside-user Synology DS220+ upgrade from v1.0.0 to v1.0.2 completed successfully, but the reporter had to work around an absent unzip utility, a restricted sudo Docker PATH, terminal input lost through nested commands, and an absent .recipe-site/updater bind source.

Version 1.0.3's transition scripts support a verified Python 3 ZIP-extraction fallback and safe Docker path discovery. The UPGRADE prompt reads from an interactive SSH terminal, and the installer/upgrader creates the private updater bind source before any migration or source-file replacement. Preflight checks for symlinks and non-directory collisions.

This preparation does not enable the in-app updater. The website must not have Docker or root privileges. On Synology, the Owner must still arrange the documented one-time root-owned DSM Task Scheduler --setup and recurring --once command. The published v1.0.2 packages remain immutable; download v1.0.3 or use a configured Owner-approved updater to obtain these fixes.

Safety boundary

The PHP website cannot run shell commands and has no Docker socket. It can write a small, strictly validated JSON request into its dedicated mailbox. A separate root-owned host script reads the mailbox at configured intervals. The updater never accepts a user-provided URL, path, shell command, or arbitrary archive name.

The host updater always fetches the current stable catalog over HTTPS from https://yourkitchenlibrary.com/downloads/stable.json, verifies its schema, release version, and SHA-256/byte size, then downloads the matching release from the fixed official download address. It unpacks the archive in an unprivileged networkless disposable Docker container, rejects symlinks and unexpected versions, and runs the documented migration-aware upgrader.

Important: SHA-256 checks detect accidental tampering/corruption relative to the HTTPS catalog. They are not an independent offline publisher signature; users must trust the official HTTPS distribution server and its certificate. For higher assurance, independently verify a separately obtained checksum.

The installer will not overwrite your .env, recipe images, MariaDB volume, or installation state. An existing site-customized www/includes/config.php is also preserved byte-for-byte. For Git installations, the upgrader detects local edits against the tracked config baseline, allows unchanged stock configuration to update normally, and refuses an upgrade if the target release also changes the config helpers. This needs a deliberate manual merge instead of losing your changes or silently retaining incompatible helpers. For archive-only installations without a trusted baseline, it conservatively preserves an existing config file.

Before modifying anything, the upgrader verifies a database backup and code snapshot. Successful upgrades run application health tests and record the new release version. Failed upgrades do not retry automatically; full recovery instructions and log files stay on the host. Updates do not silently roll back database migrations.

Special case: developer Git checkouts. The Owner updater installs verified release files but preserves .git; it does not claim the Git index/HEAD were advanced to a corresponding release commit. A developer-managed Git checkout therefore requires a separately guarded source-control reconciliation after a release upgrade. Do not use git reset --hard or a blanket git clean to make this appear clean. Inspect and preserve local configuration, media and other deviations first.

One-time Linux setup (systemd)

Open a terminal inside your installed application directory, as a user who can administer the server, and run:

sudo bash tools/recipe-site-updater-host.sh --install-dir "$PWD" --install-systemd

This sets up a systemd timer to check queued requests approximately every three minutes. It changes permissions only on the dedicated update mailbox. The website process can write requests but cannot write host status, logs, the updater configuration, or system files.

Reload Admin → Software Updates and click Check for Updates. The host service may take a few minutes to respond.

To inspect the timer:

systemctl list-timers --all | grep recipe-site-updater

To view the status file directly:

sudo bash tools/recipe-site-updater-host.sh --install-dir "$PWD" --status

If your installation path contains spaces, configure the systemd unit manually using an appropriately quoted ExecStart rather than relying on the automatic systemd writer.

One-time Synology NAS setup

Synology DSM generally uses Task Scheduler, not systemd, for privileged recurring work.

1. In your NAS SSH session, change into the actual installed application directory (for example /volume1/docker/your-kitchen-library-1.0.1).
2. Run:

bash sudo bash tools/recipe-site-updater-host.sh --install-dir "$PWD" --setup

3. Open DSM Control Panel → Task Scheduler. Create a Scheduled Task → User-defined script running as root, repeat every 5 minutes if available. Use the script printed by the setup command, substituting your actual full installation directory:

bash /bin/bash '/volume1/docker/YOUR-INSTALL-PATH/tools/recipe-site-updater-host.sh' --install-dir '/volume1/docker/YOUR-INSTALL-PATH' --once

4. Run the DSM task manually once, then open Admin → Software Updates and confirm it shows a real status. The scheduled task must remain enabled.

DSM menus and Task Scheduler intervals differ by version. The updater does not create or edit DSM system tasks itself, and it does not need to open a Docker port, shell service, or external network listener.

Where the updater keeps files

Host directory: .recipe-site/updater/

• requests/ — the only web-writable directory (UID 33).
• status.json — root-controlled status containing no secrets.
• logs/ — root-only diagnostic logs.
• host-lock — prevents concurrent upgrades.

A serious failed/aborted run may leave host-lock. Do not delete it until you confirm no updater process is still running and inspect the latest log, database dump, and code snapshot. The lock intentionally prevents blindly retrying an interrupted migration.

Before fixing an error, check:

sudo bash tools/recipe-site-updater-host.sh --install-dir "$PWD" --status
sudo ls -la .recipe-site/updater/logs/
ls -l ../recipe-site-backups/

The existing upgrade script also records full logs under .recipe-site/upgrade-logs/ and prints the actual verified backup paths.

If health checks fail after an upgrade, do not rerun the installer or manually edit database roles. Use the upgrade log and documented restore procedures in Backup and Restore or contact [email protected].

Guided upgrades of existing v1.0.0–v1.0.2 sites (v1.0.3 kit)

Version 1.0.0 cannot receive a new Owner Update page remotely; it must first be upgraded once. Download the separate v1.0.3 Easy Upgrade ZIP, extract it outside the installed site, and in an SSH terminal inside the extracted folder run:

bash UPDATE.sh

The launcher verifies the current immutable full v1.0.3 release/checksum, finds existing Synology Docker installations, and prompts for a site selection if more than one is present. It then runs the existing migration-aware preflight, displays the plan, and requires typing UPGRADE before changes. No manual code replacement or fresh database initialization is involved.

For a no-change preview: bash UPDATE.sh --dry-run. If auto-discovery misses the installation: bash UPDATE.sh --install-dir /volume1/docker/YOUR-EXISTING-SITE.

The advanced your-kitchen-library-upgrade-kit-1.0.3.zip is published unchanged. Both versions call the exact same tested legacy transition updater; the Easy Upgrade launcher only removes the need to find paths and run two commands yourself.

Previous manually modified PHP files will be included in the verified code backup and may be replaced with fixed release code. The transition preserves .env, recipes/photos, database, user accounts, and settings. Make an independent NAS backup before proceeding.

Once on v1.0.3, configure the privileged host updater separately using the Synology DSM Task Scheduler instructions above. After this one-time setup, future stable releases can be approved inside the application.

Recovery verification and remaining limits

A failed upgrade should leave diagnostic logs and verified snapshots; treat an interrupted migration as requiring investigation, not a reason to rerun a partially applied script blindly. The new v1.0.3 scripts avoid the missing updater bind-source failure before any mutation. Additional interruption, rollback and retry regression coverage remains open in issue #561. Keep an independent offsite copy and test restoration. The website Owner Update screen is not itself a privileged Docker/shell process; Linux systemd or a Synology root DSM Task Scheduler must be configured as a separate administrative step.

Requirements and limits

• Linux with Docker Engine, Docker Compose v2, Bash, curl, rsync, sha256sum and sufficient disk space.
• An internet connection to the official HTTPS release server to check for or install new updates. Manual offline upgrades remain supported using the separate release ZIP and tools/recipe-site-upgrade.sh.
• An administrator able to configure a privileged host timer or Synology task.
• Windows Docker Desktop still has preview status; the automated host updater described here is for Linux-based Docker hosts, including compatible NASes.
• Updates are Owner-approved, not unattended. Backups protect against most failed migrations but cannot guarantee recovery from a physical disk failure; keep an additional tested external backup.