Setting Up the Kiosk From Scratch

I’m going to assume you have a Windows 11 device, with two accounts: Admin and Demo. Admin has administrator access and is password protected. Demo must be non-Admin and have no password.

You are going to do most of the setup on Admin, but the kiosk will be running on Demo. This will set the demo account to Windows 11, which will lock down a lot of things.

• Note: even though you’re installing on Admin and running on Demo, all the automated stuff will be running on a separate, hidden account called SYSTEM.

Software You’ll Need

• PowerShell
  • Launch it with Administrator privileges on the Admin account.
  • You may need to run Set-ExecutionPolicy RemoteSigned to allow you to run scripts.

Install these as Admin for all users so that the Demo account can access them. They should be visible on the PATH for all users.

• Node.js
  • To run the Kiosk application.
  • Try to use the version our Kiosk is pinned to (find it in .node-version).
• Servy
  • Runs the Kiosk application as a service and monitors its health.
  • It can automatically restart the Kiosk’s proxy server in case it crashes or hangs, by having it check the server’s heartbeat.

Configuring Windows

You’ll want to change some settings on Windows before you run Kiosk mode.

Set the Display Scale

The frontend is not responsive and was built for exactly 1080x1920. You'll need to ensure the scale and resolution match that. As Demo:

1. Right-click the desktop.
2. Select "Display Settings".
3. Under "Scale & Layout" make sure the "Scale" is 100%
4. Make sure "Display Resolution" is 1080x1920.

Disable sleep and the screensaver

You’ll want to disable sleep and the screensaver to ensure the Kiosk is always on. As Admin run the following commands in an admin-level Powershell:

# 1.Disable screensaver
powercfg /change monitor-timeout-ac 0

# 2.Disable standby
powercfg /change standby-timeout-ac 0

Disable toast notification

This will disable the notifications that pop up at the bottom right of the screen. As Admin:

1. Press Windows + I
2. System > Notifications
3. Full-screen apps might already block toast notifications, but you can modify them here.

Set Windows Update to run outside of regular hours

This is so the device gets its updates, but not in the middle of the school day. As Admin:

1. Settings > Windows Update > Advanced options > Active hours
2. I suggest 8AM - 2AM for active hours.

Setting up the environment

Make sure you’ve downloaded all the software mentioned above (Node and Servy).

Download and set up the Kiosk Application

Do this on Admin.

1. Download the latest working release of the Kiosk application on GitHub.
2. Extract it into an easy to remember directory
   1. C:\apps\csss-kiosk\ should work
   2. The root of this folder should look exactly like the root of the zip, don’t place anything in different directories.
3. Lock down permissions on the Kiosk folder with this command:
   1. icacls C:\apps /inheritance:r /grant:r "SYSTEM:(OI)(CI)F" "Administrators:(OI)(CI)F"
      1. This will make the Kiosk application files not be accessible by Demo.
4. The Kiosk application should be able to be launched now, but not readable by the Demo account. You can test this by trying to run the server file. It should fail to start, but it will attempt to.

node C:\apps\csss-kiosk\server\server.js

5. You should also make the directories C:\apps\logs\csss-kiosk\ and C:\apps\scripts\csss-kiosk.

• Note: If you accidentally locked down permissions before you extracted the application use:

Expand-Archive -Path "C:\path\to\csss-kiosk\archive" -DestinationPath "C:\apps\csss-kiosk"

Set up Servy

Kiosk mode automatically restarts the browser to our web application, but Servy handles our server which handles communication with our web server and serves our static pages.

1. Set up the environment variables
   1. The frontend shouldn’t need any setup since it’s built with production variables.
   2. You’ll need to set the variables below up using Servy’s recommended way:
      1. NODE_ENV=production
      2. KIOSK_API_SECRET=<...>: This should be the web server’s KIOSK_SECRET environment variable.
      3. PROXY_TARGET=https://sfucsss.org
      4. SERVER_PORT=<...>: this can be whatever, but make sure it matches the URL the one Kiosk mode uses. At the time of writing it’s 8080.
      5. KIOSK_UPDATE_LOG_PATH=C:\apps\logs\csss-kiosk\csss-kiosk-update-log.txt
      6. KIOSK_STDERR_LOG_PATH=C:\apps\logs\csss-kiosk\stderr.log
      7. TL;DR: set the environment variables: $env:SERVY_ENVIRONMENT_VARIABLES = “NODE_ENV=production; KIOSK_API_SECRET=<...>; PROXY_TARGET=https://sfucsss.org; SERVER_PORT=<...>; KIOSK_UPDATE_LOG_PATH=C:\apps\logs\csss-kiosk\csss-kiosk-update-log.txt; KIOSK_STDERR_LOG_PATH=C:\apps\logs\csss-kiosk\stderr.log”
2. Install the Kiosk server as a service:

servy-cli install `
 --name="CSSS-Kiosk-Server" `
 --description="CSSS Kiosk Proxy Server" `
 --path="C:\path\to\node.exe" `
 --startupDir="C:\apps\csss-kiosk\server" `
 --params="C:\apps\csss-kiosk\server\server.js" `
 --startupType="Automatic" `
 --enableSizeRotation `
 --rotationSize=5 `
 --maxRotations=1 `
 --stdout="C:\apps\logs\csss-kiosk\stdout.log" `
 --stderr="C:\apps\logs\csss-kiosk\stderr.log" `
 --enableHealth `
 --heartbeatInterval=30 `
 --maxFailedChecks=3 `
 --recoveryAction="RestartService" `
 --maxRestartAttempts=5

• Don’t put any non-application files into C:\app\csss-kiosk, or else the auto-updater will delete them.
• Logs will be rotated out when they reach 5MB (rotationSize=5) and only 1 old file will be kept (--maxRotations=1)

4. DELETE THE ENVIRONMENT VARIABLES. THIS IS VERY IMPORTANT SO PEOPLE CAN’T GET THE KIOSK_API_SECRET.
5. Remove-Item Env:SERVY_ENVIRONMENT_VARIABLES
6. Clear-History
7. You probably also want to exit out of this terminal and open a new one so people can’t scroll back and see what was typed.
8. Start the service: servy-cli start --name="CSSS-Kiosk-Server".
   1. Verify it's running with Get-Service -Name "CSSS-Kiosk-Server"
9. Servy now runs the Proxy server before anyone even logs in. It will also attempt to restart the server if it goes down, with 5 max restart attempts before it gives up. You can test this by going to http://localhost:SERVER\_PORT on the Kiosk; the web app should show up.
   1. Servy also has a GUI which you can use to manage this.

Set up the auto-update script

At this point the Kiosk application’s server should be running in the background. You can now set up the auto-update script. Run this on Admin:

1. Copy the script onto the device that Demo shouldn’t be able to modify, most likely to C:\apps\scripts\csss-kiosk\csss-kiosk-autoupdater.ps1
2. Fill out the CONFIG section i.e. the lines between the hyphens.
   1. $RepoOwner: “CSSS”
   2. $RepoName: “csss-site-kiosk”
   3. $ServiceName: “CSSS-Kiosk-Server” (or whatever you named it in Servy)
   4. $AppRoot: “C:\apps\csss-kiosk” (or whatever you named it)
   5. $BackupRoot: “C:\apps\csss-kiosk_backup” (just make sure it doesn’t share the name of something else in C:\apps)
   6. $TempDir: “C:\apps\csss-kiosk_temp”
   7. $VersionFile: Join-Path $AppRoot “VERSION” (i.e. C:\apps\csss-kiosk\VERSION)
   8. $HealthCheckURL: “http://localhost:SERVER\_PORT/health”
   9. $LogFile: “C:\apps\logs\csss-kiosk\csss-kiosk-update-log.txt” (make sure this isn’t inside C:\apps\csss-kiosk)
3. Run this script manually to ensure it works. You’ll want to test:
   1. Updates with no new version.
   2. Updates with a new version. You can edit the VERSION file to be different from the latest release.
   3. Test a broken release and ensure the rollback feature works.
   4. Use powershell -ExecutionPolicy Bypass -File C:\apps\scripts\csss-kiosk\csss-kiosk-updater.ps1
4. Once you’ve verified it works, you’ll register this to run every on an interval.
   1. Move csss-kiosk-scheduled-task.ps1 into C:\app\scripts\csss-kiosk\
   2. Run

powershell -NoProfile -ExecutionPolicy Bypass -File C:\apps\scripts\csss-kiosk\csss-kiosk-scheduled-task.ps1

5. Confirm it’s running:
   1. Get-ScheduledTask -TaskName "CSSS-Kiosk-Updater"
   2. Get-ScheduledTaskInfo -TaskName "CSSS-Kiosk-Updater"
   3. You should see it will run in the next minute, then at a set interval after that.
   4. You can also check the logs, where you specified $LogFile.

Set the Demo account to use Kiosk mode

This will cause the Demo account to automatically be signed into on reboot AND launch the browser to the Kiosk application. The application will run in full-screen and it will block access to the desktop, taskbar, and system settings.

Kiosk mode keeps failing

The Windows service that manages this, AssignedAccessManagerService, may not be enabled. To enable it:

1. Hit Windows + R, type in services.msc and press Enter or click OK.
2. Find AssignedAccessManager Service in the list and double-click it.
3. Change "Startup type" to "Automatic".
4. Hit "Start".
5. Click "OK".

1. Before you do this make sure you log into Demo at least once. Log back in to Admin afterwards and follow these steps.
2. Settings > Accounts > Other Users > Set up a kiosk
3. Choose the Demo account, pick Microsoft Edge.
   1. Use "As a digital sign or interactive display".
   2. For the website URL use http://localhost:<SERVER_PORT>.
   3. Idle/session timeout indicates how long it will take for the app to go back home when there is no interaction. Set this to something like 5 minutes.
4. Now whenever you’re not logged in, Demo will attempt to log in and even after reboots.

• This will configure auto sign-in for that account on boot and locks the session to a full-screen browser.
• See FAQ’s “How do I get out of Kiosk mode?” to service the device.