Visitor sign in
A self-hosted visitor kiosk for sites that need a WWCC/VIT record and a photo at the door. Runs in one Docker container, stores everything locally in SQLite, and mirrors every sign in and sign out to a Google Sheet so someone outside the building can see who is on site during an evacuation.
- Kiosk at
/— a stepped sign in, a PIN sign in for regulars, and sign out. - Admin at
/admin— who's on site now, the visit log, recurring visitors, the people a visitor can ask for, sites, admin accounts, and system status.
Handles several sites from one container, prints a badge after sign in if you want one, warns admins before a WWCC or VIT lapses, and gives each admin their own account with two factor.
What it collects
| Guest sign in | Recurring visitor | |
|---|---|---|
| First and last name | typed each visit | on file |
| Person being visited | picked from the list | picked each visit |
| Photo | taken at the kiosk | taken at the kiosk |
| WWCC / VIT / none | typed each visit | on file |
| Mobile and/or email | at least one required | on file |
Sign out only needs a last name plus a mobile number or email, which works for both.
Quick start
git clone https://gitea.hideawaygaming.com.au/jessikitty/visitor-signin.git
cd visitor-signin
cp .env.example .env
# Generate a secret and set a real admin password before you start.
openssl rand -hex 32 # paste into APP_SECRET
$EDITOR .env
docker compose up -d --build
The kiosk is then on http://<docker-host>:8088 and the admin console on
http://<docker-host>:8088/admin.
Set ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD in .env before the first start —
they create the first admin account, once. You'll be asked to enrol two factor and set a real
password at first sign in.
Then, in the admin console:
- Sites → rename the first site, add more if you have them, and turn badge printing on.
- People to visit → pick a site, then paste or upload your staff CSV
(see
docs/hosts-sample.csv). - Recurring visitors → add anyone who comes regularly. A PIN is generated and a printable card opens straight away.
- Admins → invite the rest of the front office.
Working from Windows, deploying to Ubuntu
Develop on Windows, run the container on the Ubuntu host. Two scripts are included:
# in PowerShell, inside the visitor-signin folder
.\push-to-gitea.ps1
Or double-click push-to-gitea.bat. If PowerShell blocks the script, run
powershell -ExecutionPolicy Bypass -File .\push-to-gitea.ps1. On the Ubuntu host,
./push-to-gitea.sh does the same thing.
.gitattributes forces LF endings for everything except the .ps1 and .bat helpers, so the
shell scripts and the Dockerfile still work after a round trip through a Windows checkout —
otherwise gen-cert.sh fails on the host with a confusing \r: command not found.
Deploy on the Ubuntu host with:
git clone https://gitea.hideawaygaming.com.au/jessikitty/visitor-signin.git
cd visitor-signin && cp .env.example .env && nano .env
docker compose up -d --build
docker compose on Windows works too if you have Docker Desktop, but the camera, printing and
the data/ permissions all behave more predictably on the Ubuntu host.
Several sites, one container
Each site has its own name, its own list of people to visit, and its own badge settings. Recurring visitors are either tied to one site or welcome at all of them.
Point a kiosk at a site once, during setup, with http://host:8088/?site=front-gate. The tablet
remembers the choice, so the address bar no longer matters. If you skip that, the kiosk asks
which site it is on first use — and with only one site set up, it never asks at all.
Sign in, sign out and the "already signed in" check are all scoped to the kiosk's site, so the same person can be signed in at two sites at once without the system arguing about it.
An admin account can be limited to a single site. Those admins see only that site's visitors, staff list and log, and cannot touch the others.
Badge printing
Turn it on per site under Sites → Edit. After a visitor signs in, the kiosk loads the badge into a hidden frame and prints it — one label, no dialog on most kiosk setups. The badge shows the site, name, who they are visiting, time in, WWCC/VIT status (or a boxed No WWCC / VIT), the photo if you want it, and an optional line of your own text.
Set the label size in millimetres to match your stock. Type scales with the smaller dimension, so small labels stay legible. Common sizes:
| Stock | mm |
|---|---|
| Card size | 86 × 54 |
| Brother DK-11202 shipping | 100 × 62 |
| Brother DK-11209 small address | 62 × 29 |
| Dymo 99014 shipping | 101 × 54 |
Use Preview badge to check the layout in a browser before committing a roll to it. The kiosk browser needs the label printer set as its default, with margins off and scaling at 100%.
Admins can reprint from the On site list, and the visitor gets a "Print the badge again" button on the confirmation screen if the first one jams.
WWCC and VIT expiry warnings
Give a recurring visitor an expiry date and the console watches it. Inside
EXPIRY_WARNING_DAYS (28 by default) their 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 to have at the desk, not a door the software should slam. Site-scoped admins only see warnings for their own site.
Admin accounts and two factor
Each admin signs in with their own email address and password.
- Roles. Owner manages admins and sites. Admin handles day to day work, optionally limited to one site.
- Two factor. With
ADMIN_REQUIRE_2FA=true(the default) every admin enrols an authenticator app at first sign in — a QR code appears, they scan it, and eight one-shot recovery codes are issued. Standard TOTP, so Google Authenticator, Authy, 1Password, Bitwarden and the rest all work. - Domain limits. Set
ADMIN_ALLOWED_DOMAINS=yourschool.vic.edu.auand both invitations and sign in refuse anything else. Subdomains of a listed domain are accepted. - Recovery. An owner can reset another admin's password (a temporary one is shown on screen, and they must change it at next sign in) or clear their two factor so they can re-enrol on a new phone.
- Lockout. Six wrong passwords locks that email address for 15 minutes.
If every owner loses access, stop the container, clear the admin_users table with
sqlite3 data/visitors.db "DELETE FROM admin_users;", and start it again — the bootstrap
account is recreated from .env.
The camera needs HTTPS
Browsers refuse camera access on a plain http:// address unless it is localhost. On an
internal IP the kiosk will show a message telling the visitor the camera is blocked. Pick one:
Option A — reverse proxy (best if you already run one). Terminate TLS at Nginx Proxy
Manager, Traefik, or Caddy and point it at the container. Then set TRUST_PROXY=true and
SECURE_COOKIES=true in .env.
Option B — self-signed certificate in the container.
./scripts/gen-cert.sh visitors.local 192.168.1.50 # your hostname, then any IPs
# set HTTPS_ENABLED=true in .env
docker compose restart
Then install data/certs/server.crt as a trusted root certificate on each kiosk tablet,
otherwise the browser warning appears every morning.
Option C — run the browser on the same machine as the container and point it at
http://localhost:8088. No certificate needed.
Google Sheet mirroring
Every sign in and sign out appends a row. If Google is unreachable the row is queued in the database and retried every minute, so a dropped internet connection never blocks the front desk.
-
In Google Cloud Console, create a project and enable the Google Sheets API.
-
Create a service account, then create a JSON key for it and download the file.
-
Create the spreadsheet you want to use. Share it with the service account's email address (it ends in
.iam.gserviceaccount.com) with Editor access. This step is the one people forget — without it every write returns a permission error. -
Copy the spreadsheet id out of the URL:
docs.google.com/spreadsheets/d/THIS_PART/edit. -
Put the key file at
./secrets/google-service-account.json(compose mounts./secretsread-only), then in.env:SHEETS_ENABLED=true SHEETS_SPREADSHEET_ID=THIS_PART SHEETS_TAB_NAME=Visitor log GOOGLE_CREDENTIALS_PATH=/secrets/google-service-account.jsonIf you would rather not mount a file, base64 the key instead —
base64 -w0 key.json— and put the result inGOOGLE_CREDENTIALS_B64. -
Restart, then Admin → System → Test the sheet connection. The header row is written automatically the first time.
A tab name with spaces is fine. The sheet is a mirror, not the source of truth — nothing reads back from it. Every row carries the site name, so one sheet covers all sites; filter by the Site column during an evacuation.
Recurring visitors and PINs
The mobile number is the username, and the PIN is four digits. PINs are stored encrypted with
APP_SECRET rather than hashed, so an admin can reprint a lost card without resetting it. Four
digits is only 10,000 combinations, so hashing would add nothing against anyone holding a copy
of the database — the real protection is the lockout: five wrong PINs on a number locks it for
15 minutes.
Changing APP_SECRET makes every stored PIN unreadable. If you have to change it, reissue
PINs from the admin console afterwards.
Where the data lives
Everything is under ./data on the docker host:
data/
├── visitors.db SQLite: sites, visits, recurring visitors, hosts, admins, retry queue
├── visitors.db-wal write-ahead log — back this up alongside the .db
└── photos/2026/08/ JPEGs, foldered by year and month
Photos never leave the host. The sheet records only whether a photo exists. They are deleted
automatically after PHOTO_RETENTION_DAYS (90 by default), and only the admin console can view
them.
To back up: docker compose stop && tar czf visitor-backup-$(date +%F).tar.gz data/ && docker compose start.
Settings worth knowing
| Variable | Does what |
|---|---|
REQUIRE_PHOTO |
false lets a visitor continue if the camera fails |
AUTO_SIGNOUT_TIME |
e.g. 18:30 — closes off anyone still shown as on site. Blank to disable |
PHOTO_RETENTION_DAYS |
0 keeps photos forever |
HOST_PORT |
port published on the docker host, default 8088 |
EXPIRY_WARNING_DAYS |
how far ahead to warn about a WWCC or VIT, default 28 |
ADMIN_REQUIRE_2FA |
false makes two factor optional per admin |
ADMIN_ALLOWED_DOMAINS |
comma separated; blank allows any email domain |
The kiosk returns to the home screen after two minutes of inactivity so the next visitor never sees the last one's details.
Running without Docker
npm install
DATA_DIR=./data APP_SECRET=$(openssl rand -hex 32) ADMIN_PASSWORD=secret npm start
Node 20 or newer.
A note on evacuation use
The Google Sheet is the offsite copy, but it only helps if someone can open it on a phone during an evacuation. Bookmark it on the relevant phones, check it after setup, and check it again occasionally — a service account key that has been revoked will queue rows silently until someone looks at Admin → System.
Created by: Jess Rogerson (yelling commands at Claude.AI)