visitor-signin/docs/ADMIN-GUIDE.md

Site Sign In — Administrator Guide

Last updated: 4 October 2026

A plain-language guide to the Site Sign In admin console: checking who is on site, fixing a stuck sign-in, keeping hosts and sites current, and getting badge printing going again. No command line needed for anything in here.

Getting in

The console lives at https://<your server>:8443/admin, and you open it from a staff machine. The kiosk deliberately has no link to it — a kiosk is a public terminal, so administration does not belong on it.

Sign in with your own email address and password. At your first sign in you will be asked to set a real password and to scan a QR code into an authenticator app (Google Authenticator, Authy, 1Password and Bitwarden all work). Save the eight recovery codes somewhere you can get to without your phone — each works once.

Two roles:

Role	Can do
Owner	Everything, including adding admins and sites
Admin	Day-to-day work; can be limited to a single site, and then sees only that site's visitors, staff list and log

If you are locked out, six wrong passwords locks that email address for 15 minutes. An owner can reset another admin's password (a temporary one appears on screen) or clear their two-factor so they can re-enrol on a new phone.

A browser certificate warning means that machine does not yet trust the local authority. Install it from System → Certificate, or browse to http://<your server>:8080/ca.crt.

Who is on site right now

On site is the tab you will live in. It lists everyone currently signed in, with their host, the time they arrived and how long they have been here.

Three things you can do from each row:

• Sign out — for the visitor who walked out without touching the kiosk.
• Reprint the badge — for a jam, a mis-feed, or a badge left on a desk.
• Make regular — turns a guest into a recurring visitor. It takes their name, company, mobile, email and check details straight from the visit, issues a PIN and opens the printable card. Their sign-in photo is kept as their profile photo, so from the next visit the kiosk skips the camera. The button only appears for someone who gave a mobile number.

The matching offsite copy is the On site now tab of the Google Sheet. It is rewritten in full every time anyone signs in or out, so it holds current occupants only, never history. The top row shows the head count and the time it was last updated — if that time is stale, the writes are queuing.

Visit log holds the complete history: searchable (it matches on company, so you can pull up every visit from one contractor) and downloadable as CSV. That history stays in the application and is never sent to Google.

Anyone still showing as on site at AUTO_SIGNOUT_TIME is closed off automatically overnight.

Keeping the lists current

Two lists need an eye kept on them: the people a visitor can ask for, and the regulars who sign in with a PIN.

People to visit. Pick a site, then paste or upload your staff CSV (docs/hosts-sample.csv shows the shape). This is the list the kiosk offers a visitor, so a departed staff member left on it is the usual cause of a badge naming the wrong host.

Recurring visitors. Each saved person is one record, and their mobile number, email address and PIN must all be unique. The mobile number is the username; the PIN is four digits.

To do this	Use this
Issue a fresh random PIN	New PIN on the list
Set a specific PIN, or read back the current one	Edit — leave the PIN box blank to keep the current one
Stop someone signing in, but keep their record	Untick Active in Edit
Delete them for good	Remove — the PIN stops working and the stored photo goes
Stop the kiosk asking them to pose	Add a photo in Edit, from the camera or a file

Removing someone keeps their visit history: visits store the name, contact details and host in their own columns. It does not sign them out if they are currently on site — the confirmation says so, and their visit can still be closed at the kiosk with their last name and mobile number.

Five wrong PINs locks that mobile number for 15 minutes. Saving the record clears the lockout, under both the old and the new number.

WWCC and VIT expiry. Give a recurring visitor an expiry date and the console watches it. Inside 28 days the row turns amber; past the date it turns red, a count appears on the Recurring visitors tab, and a banner sits across the top of every screen. Nothing is blocked automatically — an expired check is a conversation at the desk, not a door the software slams.

Settings worth knowing

Almost everything a site needs sits under Sites → Edit. Each site has its own staff list, its own badge settings and its own look.

Setting	What to know
Badge printing	Turn it on per site. With Print from the server ticked, the server renders the badge and pushes it to the printer, so the kiosk tablet needs no driver and shows no print dialog
Roll loaded in the printer	Must match what is physically in the machine. This is the single most common cause of a refused job
Label stock	A shortcut that fills in size, roll type and colour option. It is not itself saved, which is why it can appear to revert
Rotation	0° lays the badge across the 62 mm width; 90° turns it for a label that hangs from its short edge. Check the bitmap preview — only one will suit how you hang them
Photo settings	Error diffusion is the default and much the best for faces. Preview the photo settings renders a real visitor photo at several settings side by side
Banner and colours	PNG with a transparent background, up to 2 MB. The editor shows the contrast ratio as you type — aim for 7:1 on a screen people read standing up

Before committing a new roll, use Bitmap preview (shows the exact image that will be sent) and Test print on the site card.

The evacuation sheet

The Google Sheet exists for one job: so somebody standing in a car park can see who is in the building. Check it from System → Test the sheet connection, which also shows the service account address and the last successful write.

Bookmark the sheet on the phones that would actually be used in an evacuation, and confirm it loads for them, not just for you. Check it again occasionally — a revoked key or changed sharing queues rows silently, and the head count and Updated time in the first row are the giveaway.

When badges stop printing

First, the reassuring part: sign in still completes. The visitor is recorded, the kiosk falls back to its own browser print dialog, and the failure is shown against the site in Sites with the reason. You can reprint any badge from the On site list.

Work through these in order — the first two account for nearly every case.

1. Does the roll setting match the roll? Open Sites → Edit → Printer and compare Roll loaded in the printer with what is actually in the machine. A DK-22251 must be set as the black/red roll even when nothing on the badge is red. The printer's own message — Black/Red on White paper is installed now. Change it to Monochrome media — sounds like a driver setting but means swap the roll or fix this field.

2. Continuous or die-cut? 62 means a continuous roll cut to length; 62x100 means pre-cut labels. Sending one to the other kind is refused as a wrong roll.

3. Can the printer be reached? It needs a fixed IP — a DHCP lease change silently stops badges. Check the address under Sites → Edit → Printer.

4. Press Test print on the site card. A failed test shows the printer's own words rather than a summary, and Diagnostics shows exactly what would be sent.

5. Ask the printer what it has loaded, on the docker host:

   docker compose exec visitor-signin node scripts/printer-status.mjs
   

   The QL-820NWB is write-only over port 9100, so it often will not answer. When it doesn't, Brother Status Monitor on a PC with the printer installed gives the exact reason a job was refused — more than anything on the server can tell you.

6. Still stuck? docker compose exec -it visitor-signin node scripts/print-probe.mjs sends one label per roll id and asks you after each whether anything came out. The -it matters: it needs a terminal.

Everything else that goes wrong

What you see	What it means	What to do
Browser warns about the certificate	That device does not trust the local authority	Install it from System → Certificate. On iPad there is a second, separate step: Settings → General → About → Certificate Trust Settings
Sheet says The caller does not have permission	The spreadsheet was never shared with the service account	System shows the address. Share the sheet with it as Editor. This is the cause nine times in ten
Head count on the sheet looks stale	Writes are queuing	System shows the last successful write and any error. Rows retry every minute and are never lost
An admin cannot sign in	Six wrong passwords locks the address for 15 minutes	Wait, or have an owner reset the password
An admin lost their phone	Their authenticator is gone	An owner clears their two-factor; they re-enrol at next sign in
A regular's PIN is rejected	Five wrong attempts locks that mobile number for 15 minutes	Open their record and save it — that clears the lockout
The kiosk asks which site it is on	It was never pointed at one	Visit http://<server>:8088/?site=<site-slug> once; the tablet remembers
Someone is still on site who left hours ago	They never signed out	Sign them out from the On site list. AUTO_SIGNOUT_TIME catches the rest overnight

Two things to be careful with

Changing APP_SECRET makes every stored PIN unreadable. If it has to change, reissue PINs from the console afterwards.

Starting a new certificate authority means every kiosk device has to trust the new one. Renew the server certificate is the safe option and touches no devices.

If you edit .env on the host, bring the container back with docker compose up -d, not docker compose restart — restart reuses the old environment and the change appears to do nothing.

---

Created by: Jess Rogerson (yelling commands at Claude.AI)