Skip to content

Updating the Kiosk

Jump to bottom
Jon Andre Briones edited this page Aug 26, 2026 · 5 revisions

This section outlines the workflow to update the Kiosk application. A couple of notes:

  • You don’t need to make a tagged release if changes don’t affect end-users. For example, if you’re updating a build configuration or some developer tools, those don’t need to be released onto the Kiosk.
  • You can do this one of two ways: through the GUI on GitHUB or on the CLI. I suggest the CLI.
  • Here are some guidelines on which version to bump:
    • major: Something was changed and you’ll need to hop on the Kiosk to make it run.
      • Server environment variables changed and Servy needs to be updated.
      • VERSION file format changed.
      • Node.js version bump.
      • Auto-updater needs to be modified.
    • minor: Changes probably affect the end-user and the auto-updater can handle the change.
      • Updating or changing out the frontend framework.
      • Rehauling the UI/design.
      • Complete features added, removed, or heavily modified.
    • patch: Changes that don’t really change the end-user experience or fix bugs. The auto-updater should be able to handle these.
      • Minor UI tweaks.
      • Library/dependency bumps.
      • Bug fixes.
  • The tag will have a "v" in front of it, the npm version will not, just make sure they are the same otherwise.

Creating a Tagged Release

The first step is to create a tagged release package on GitHub. There is a GitHub Action in the repository, .github/workflows/release.yml, that triggers when a tagged release is pushed/created on GitHub and creates a new release package. This should be done on your own device, not the Kiosk.

Option 1: Git CLI (recommended)

  1. Make sure you’re on master branch and have no uncommitted changes.
    1. Double-check you have the latest version of master checked out i.e. run git pull.
  2. Run the command npm version <major/minor/patch> --no-git-tag-version in the project root.
    1. --no-git-tag-version ensures you don’t create a tag for the backend.
  3. BOTH server/package.json and frontend/package.json should have the same version.
  4. Add and commit the updated files.
    1. git add package.json package-lock.json
    2. git commit -m “v<major>.<minor>.<patch>”
  5. Add the tag and push it up to GitHub.
    1. git tag -a v<major>.<minor>.<patch> -m "Release v<major>.<minor>.<patch> # or whatever message you want
    2. git push --follow-tags
  6. You’re done! The GitHub action should build and add the package to this release.

Option 2: GitHub

Note: This will create a release and then the build will trigger, so the autoupdater may see a release, but not the package. This just means the auto-update script will fail and you'll need to wait until it tries again.

  1. Go to the repository on GitHub.
  2. Click on “Create a new release”.
image
  1. Create a new tag on master.
image
  1. Create the new tag. We’ll try to use semver versioning rules. It doesn’t really map well since the Kiosk shouldn’t be a dependency of something else and we only change versions when something affects the end-user.
    1. The tag should be the form v<major>.<minor>.<patch>.
  2. Generate release notes. This is optional, but it’s nice to have a summary of the changes, plus you can see who your top or new contributors are.
  3. The title will probably be the same as the tag, but you can name it whatever.
  4. You’re done! The GitHub action should build and add the package to this release.

Auto-update script

The auto-update feature runs every so often and attempts to update the entire Kiosk application.

  1. Checks GitHub for a new tagged release.
  2. Compares it to the current release.
    1. It’s written in C:\apps\csss-kiosk\VERSION
  3. If the version is different (NOTE: not higher, just different) then it attempts to update.
    1. It will pull the release package (*.zip) and the checksum, if available (*.zip.sha256).
    2. Check that the checksum matches, fails if it doesn’t. If the checksum doesn’t exist it will skip this step.
    3. It will stop the Kiosk application service, backup the current application folder, and put the new version in the correct place.
    4. It will then re-launch the Kiosk application service and test its health 5 times, in intervals of 3 seconds.
      1. The health test just polls /health on the Kiosk application server. If it returns 200 it passes the test.
    5. If it passes a single health check the updater should finish writing its logs and then exit.
  • Note: the backup files will still linger until the next update. 6. If it fails all 5 health checks then the backup will be put back in its place.

The logs for the updater will be rotated when they reach bigger than 5MB. Once larger than 5MB, it will be renamed to $LogFile.old and a new log file will be started. If the current log file reaches 5MB and there is an old log file then the old log file will be overwritten and lost.

Updating the auto-update script

  1. Log in to Admin
  2. Replace the auto-update script on the device where it’s sitting
    1. If this guide was followed it’s most likely at C:\apps\scripts\csss-kiosk\csss-kiosk-autoupdater.ps1
  3. Do the manual tests again to ensure it works.

Clone this wiki locally