Android test APK release workflow

This procedure explains the WordPress plugin upload, one-time worker setup, live build progress, APK download and full debug archive. It names the remaining physical-device verification requirements.

What is automated

On a new HSLG presentation plugin upload, WordPress compares the release's approved Android source checksum with the last native payload. If nothing native changed, the plugin update finishes without starting Gradle or opening an unnecessary build window. When the source changed, the next administrator page displays a build progress window. The WordPress documentation publisher continues to run independently and updates its pages using revisions. Installing a documentation-only ZIP must not manufacture a new APK build.

The progress window is an activity and troubleshooting tool, not a request for another manual approval. It shows the queue state, current compiler step, a progress bar and the most recent build output. The compiler runs outside WordPress and continues if the window is closed or the browser disconnects. The browser refreshes the visible result roughly every two seconds. The worker checks for new jobs once per minute, so the first queued phase may persist briefly without indicating a failure.

First-time preparation

The build host must already have the restricted Android toolchain in /home/media/.hslg-build/: its private env.sh, Node.js, pnpm, Android SDK and Gradle. The infrastructure test reached BUILD SUCCESSFUL on the Ubuntu host after setting Android minimum SDK 26. Those files stay on the server; the user does not need to ZIP or upload them to ChatGPT. The standalone build worker requires one deliberate installation command by the media user, not by root:

bash /home/media/public_html/wp-content/plugins/hslg-presentation/worker/setup-worker.sh

This command is needed only once unless cron or the worker environment is lost. It adds a job-checking entry to the media user's own cron, not to Virtualmin's configuration. If PHP CLI or cron is unavailable, the script reports the missing prerequisite without changing system services. Do not run the script as root, grant the WordPress service sudo, or move the build directories inside public_html.

Updating the presenter

In WordPress administration, open Plugins, select the new HSLG Presentation ZIP, and replace the installed version. Continue to the WordPress admin screen if the uploader redirects to an installation summary; the new plugin needs to load to detect its build manifest. If the native payload is new, leave the progress modal open to watch the build or close it and return later. The interface never asks for a file to be uploaded manually. For unchanged native source, only the plugin and related documentation change; no build job is created.

When compilation completes, select Download Android test APK. Install the package on the Android phone using the normal Android package installer, accepting device prompts only when you understand the development-build risk. A test/debug APK is not a Play Store release. The app ID is uk.hslg.app, and Android 8.0/API 26 is the supported minimum because the native QR scanner library requires it. If a previously installed APK was signed with a different debug key, Android may refuse to upgrade; preserve the original key or remove the incompatible development app after reviewing any local test data.

What to test on the Android phone

Open the actual app, navigate to Account & Settings → Device Checks, then test each available native capability. The network status should reflect Wi-Fi or mobile-data changes; disconnect networking and confirm Retry does not fabricate a server success. Haptic feedback should cause a physical vibration when the device supports it. QR scanning should prompt for camera permission, display the genuine scanner and handle cancellation without inventing a scanned table. Portrait and keyboard behaviour should match Android system controls. Deep-link behaviour additionally requires that the approved HTTPS domain serves a matching Android asset-links association file; a compiled intent filter alone is not proof of verified links.

The browser presenter uses fictional device-service responses to demonstrate the expected user experience on a desktop. It does not prove that Android permissions, the camera or vibration are available. Record actual phone model, Android version, steps, observed result and failure reproduction in the release record before treating a feature as device-verified.

Reading the progress output

Build queued means WordPress recorded the approved payload; the media-user cron process has not claimed it yet. Building native Android APK means the worker began installation, TypeScript compilation, Vite bundling, Capacitor synchronisation or Gradle tasks. The percentage represents completed stages, not a countdown. Android APK ready means the signed APK exists in the restricted private directory and matches its recorded SHA-256 checksum. Android build failed means the worker stopped and recorded the reason; it does not silently produce a WebView-only substitute. Build blocked means the release manifest, source checksum or security conditions failed validation and no untrusted compiler operation should proceed.

After success or failure, download Full build debug ZIP. It includes the full compiler log, bounded diagnostic report and, when resolved, the dependency lockfile needed to reproduce missing-library failures. Share it back with the development assistant when diagnosing a failed compile. Do not post it publicly without checking the contents, as compiler logs may contain private paths and internal dependencies.

Troubleshooting and escalation

If the window remains queued beyond a normal worker poll, confirm the one-time installer was run, that the media user's scheduler is running, and that PHP CLI is available to that same account. WP-CLI is optional because the plugin includes a restricted local PHP-CLI fallback. Avoid applying sudo or changing Virtualmin services just to bypass a queue error. If the builder cannot access /home/media/.hslg-build/, restore private-user ownership and permissions from approved environment records. If pnpm cannot download a dependency, preserve its error output; the worker leaves downloaded dependency caches for later retries. The Presentation administration screen retains download links for the latest verified APK and debug ZIP; closing the modal does not discard them. If Gradle complains that the barcode scanner needs SDK 26, the reviewed minimum SDK pin may have failed and the release must be corrected rather than using an unsafe override.

If no modal appears after a presenter-only or documentation-only update, that is expected. If a new payload should have built but no modal appears, confirm the new HSLG Presentation plugin version is active and the manifest is present. Do not delete WordPress posts, rebuild the WordPress database or alter the customer-data tables to fix a native build. The only expected cleanup deletes the worker's disposable compilation workspace after archiving logs and artifacts.

Failure recovery and retry in WordPress

A native source checksum is not proof of a completed APK. The previous coordinator saved the checksum when a job started, preventing a reinstall from launching another attempt after failure. The corrected workflow distinguishes queued, running, failed, blocked and verified success. Success requires a signed APK at the recorded private path and a matching SHA-256 digest.

If a build fails, leave its debug ZIP available. Open the Presentation administration panel and choose Retry failed Android build; this queues a fresh attempt using the same approved source package. A newer presenter release also retries an incomplete native payload automatically. A normal page refresh does not create infinite builds, and an active running build cannot be duplicated by the retry action. If the status remains failed, download the new diagnostic ZIP and supply it to the development process without uploading the entire npm/Gradle cache.

If a completed APK disappears or fails checksum validation after an outage, the system treats it as incomplete. Restore a verified backup if available or run another build; never mark an absent binary as delivered. The release-history and disaster-recovery guides must record the worker installer, the media cron entry, the location of the private artifacts and the verification procedure for each release.

23 October 2026 — Vite scanner import failure and correction

The first real HSLG WordPress-triggered build stopped during Vite bundling, after npm dependencies and the shared TypeScript/UI stage completed. Its debug log reported that BarcodeScanner was not exported by the installed @capacitor/barcode-scanner@3.1.3 entry point in CapacitorDeviceServices.ts. That archive exports CapacitorBarcodeScanner; the mobile adapter in presenter v2.9.3 calls CapacitorBarcodeScanner.scanBarcode instead. The warning about Vite's older @types/node peer dependency was not the terminating error. This correction does not need a new SDK download or a root SSH command.

Install the corrected HSLG Presentation plugin ZIP through WordPress as normal. The changed verified mobile payload triggers a new Android job; it cannot recycle the previous failure as a completed APK. Check the administrator modal for Vite bundle, Capacitor Android, Gradle and final signed APK verification. A Vite success alone does not prove that Android compiled. On failure, download the new full debug ZIP from the Presentation administration page. Only a signed APK passing the checksum check is ready for physical Android testing.