DocumentationBack to app →
All guides

Deployment & rollout

On-site install target: under 10 minutes

What the clock includes: From power + network live to first successful tap (or first successful POST /api/gate-events with allowed: true on a test tag).
What it excludes: Travel, parking, client chit-chat, troubleshooting a dead port, fixing site Wi‑Fi captive portals, and first-time Python dependency installs on the edge device — budget those separately.

Hardware Profile: For Unattended Gate (24/7 access), we use a Raspberry Pi (Zero 2W or 4) paired with a WalletMate II Mini (for NFC/VAS support). For Manned Gate (staffed), a simple USB NFC tag reader connected to any edge host (laptop/mini-PC) is used.

Lab / staging note: On an edge controller or host, pip install -r requirements.txt for the access-engine venv often needs 20 to 30 minutes (network, wheels, occasional compiles). Run that in the lab, confirm member-access.service starts, and smoke-test taps before the site visit — it is not an on-site activity if you want the under-10‑minute clock to hold.

The only way to hit <10 min reliably is to remove decisions and typing from the visit. Almost everything is pre-staged before you walk in.

1. Time budget (example)

PhaseTargetNotes
Unpack, mount/plug reader + controller~2 minCables pre-labeled; reader already paired in lab
Power + Ethernet (or agreed Wi‑Fi)~1 minPrefer Ethernet; Wi‑Fi only if SSID/password known in advance
Boot / VPN node up~1–2 minDevice should already be on Tailscale; just needs internet
Smoke test (HTTPS + one gate call)~2–3 minScripted or one bookmarked URL
Optional: show staff the LED / screen / “deny” test~1–2 minSkip if client is in a hurry; do remotely later

Slack is tiny. If anything needs lookup (facility UUID, accessPointId, secret rotation), you’ve already lost the 10-minute goal.

2. Pre-arrival checklist (mandatory)

Do this in the office / lab, not at the venue.

#Task
P1Golden image on the controller: OS patched, reader driver/stack installed, gate client installed, auto-start on boot; Python venv deps fully installed (pip install -r requirements.txt — budget 20 to 30 minutes on first run for some devices; verify in lab, not on site)
P2Tailscale joined; hostname matches fleet registry; ACLs allow support SSH
P3Config file or env already on device — no paste on site. For access-engine: pre-built device.env (see device.env.example) and sudo ./deploy.sh in lab; portal access point row must match the gate hostname/serial declared in device.env (same identifiers the stack uses for heartbeat and tap correlation). For web POST /api/gate-events flows, same idea: facility / access point / ingest secret (or equivalent) baked before the visit
P4Access point row created in portal (Reader admin); serial/name matches label on hardware
P5Test member (or test nfc_uid) in DB; verified grant + deny in lab on this exact unit
P6Physical kit packed: labeled PSU, Ethernet cable (length known), spare cable, test tag, zip ties, label with device_id + support #
P7Deployment log row drafted: customer, location, device_id, deployed_by — fill deployed_at on site

Optional but high leverage: QR on the device linking to an internal “this unit” page (facility slug, support runbook) — still no secrets on the QR.

3. On-site sequence (do not reorder)

  1. Place reader and controller; one cable path (no rerouting mid-install).
  2. Power controller; Ethernet first choice.
  3. Wait for online: Tailscale ping from your phone/laptop to hostname, or health check script green.
  4. One smoke test: e.g. run your existing POST gate test with test tag → expect allowed: true; unknown tag → allowed: false.
  5. Handoff: show staff where power cycles; log deployment (time, notes).

If step 3 fails: have a printed fallback — “call X” / “hotspot SSID Y” — don’t burn the 10 minutes debugging site LAN policy without a contract.

4. Design rules that protect the 10 minutes

RuleWhy
No typing UUIDs on siteError-prone; use pre-baked config per device_id
One network pathEthernet dongle + known-good cable beats “maybe Wi‑Fi works”
Same reader SKU in the field as in labDriver and latency surprises disappear
Secrets not in photos or SlackUse refs + vault; config pushed via secure channel before visit
Idempotent bootPower loss at venue shouldn’t require manual start

5. When 10 minutes is the wrong goal

  • First install at a new venue type (new firewall, new ISP kit) — treat as discovery; book 45–60 min once, then standardize.
  • Credential enrollment at the door (bulk NFC UID linking) — that’s a different workflow; either pre-enroll or schedule separately.

6. After the visit (5 minutes, can be remote)

  • Finalize deployment log (retrieved_at if pulled same day).
  • Note Tailscale IP if it changed (shouldn’t).
  • Ticket: facility slug + accessPointId + device_id for support continuity.