PhotoDithering

README.md

@@ -179,10 +179,41 @@ the widest roll it will accept — the console warns you if you enter anything w
 | DK-11208 | 38 × 90 mm die-cut | Narrower; turn the photo off |
 | DK-11209 | 29 × 62 mm die-cut | Name and host only |
 
+**A DK-22251 must be set as the black/red roll even if nothing on the badge is red.** The printer
+refuses a monochrome job on two-colour tape, saying *Black/Red on White paper is installed now.
+Change it to Monochrome media.* The roll setting controls how the job is built, not just its
+colour.
+
+### Photos on the badge
+
+A thermal printer has one bit per dot: every pixel is either burnt or not. A photo therefore has
+to be reduced to pure black and white, and how that is done makes the difference between a
+recognisable face and a few solid blobs.
+
+Under **Sites → Edit → Badge printing**:
+
+| Setting | What it does |
+|---|---|
+| Error diffusion | Scatters the rounding error into neighbouring dots, so mid tones survive as a pattern. The default, and much the best for faces. |
+| Hard threshold | Every pixel darker than the cut becomes solid black. Crisp for line art, ruinous for photographs. |
+| Leave it to the driver | Sends greyscale and lets `brother_ql` decide. |
+| Threshold | Where the cut falls. Higher is darker. |
+| Contrast | Applied before the reduction. Webcam photos are flat and flatten further at one bit, so a lift of 20 to 30 usually helps. |
+
+**Preview the photo settings** renders the most recent real visitor photo at several settings side
+by side, so the choice is made by eye. The halftoning happens in the server's renderer, not in the
+printer driver, so the preview and the printed label are the same image.
+
+**Tell it which roll is loaded.** *Roll loaded in the printer* under **Sites → Edit → Printer**
+must match what is physically in the machine. A two-colour job sent to a plain roll is refused
+outright: the printer shows **Wrong Roll Type** and nothing comes out. The setting is separate
+from the red styling option on purpose — a design choice should not silently change the media
+type the printer is told to expect.
+
 **The red option.** Tick *Print the heading and the no-check warning in red* and the site name
 and the **No WWCC / VIT** box print red instead of black, which makes a visitor without a check
-obvious across a room. It only works on a DK-22251 roll — on any other roll the printer renders
+obvious across a room. It needs the roll setting above to be the DK-22251; with a plain roll
-it as grey. Two-colour printing is also far slower than black alone (Brother rate it at roughly
+selected the badge is drawn in black instead and the console says so. Two-colour printing is also far slower than black alone (Brother rate it at roughly
 15 labels a minute against 110), which is irrelevant for one badge at a time but worth knowing.
 
 ### Printing from the server
@@ -206,6 +237,55 @@ it is laid out along the length and turned before printing, which is what you wa
 hangs from its short edge. Set it per site and check the bitmap preview — the two look very
 different and only one will suit how you hang them.
 
+**Label stock** at the top of the badge settings is a shortcut that fills in the size, the roll
+type and the colour option. It is not itself a saved setting — the three fields it fills are what
+get stored, which is why it can appear to "revert" when the same dimensions describe two rolls.
+
+**Ask the printer what it has loaded.** This is the first thing to run when a job is refused:
+
+```bash
+docker compose exec visitor-signin node scripts/printer-status.mjs
+```
+
+It reports the media width, whether the roll is continuous or die-cut, any error the printer is
+holding, and the roll id that matches.
+
+**It does not work on every printer.** Many Brother network print servers are write-only on port
+9100: they accept jobs but never answer a status request, even though the same printer reports
+happily over USB. The QL-820NWB is one of them. When that happens, **Brother Status Monitor on a
+PC with the printer installed is the thing to use** — it gives the exact reason a job was refused,
+in plain words, which is more than anything on the server can tell you. `brother_ql`'s network
+backend never reads the socket at all, so it reports success no matter what the printer does.
+
+If the printer will not answer, work through the possibilities one at a time:
+
+```bash
+docker compose exec -it visitor-signin node scripts/print-probe.mjs
+```
+
+It sends one label per roll id and waits for you to say whether anything came out, then moves on.
+The `-it` matters: it asks questions and needs a terminal.
+
+**Diagnostics from the command line.** When the console is not enough:
+
+```bash
+docker compose exec visitor-signin node scripts/print-test.mjs        # render and print
+docker compose exec visitor-signin node scripts/print-test.mjs --dry  # render only
+docker compose exec visitor-signin node scripts/print-test.mjs --label 62x100
+```
+
+It prints the settings it is using, the exact `brother_ql` command, and the printer's full reply.
+`--label` and `--rotate` override the saved settings for one run, so alternatives can be tried
+without saving anything.
+
+**Continuous versus die-cut matters.** `62` means a continuous roll cut to length; `62x100` means
+pre-cut labels. Sending one id to the other kind of roll is refused as a wrong roll, and this is
+the most common cause of that error after the two-colour setting.
+
+**Diagnostics.** The site card has a **Diagnostics** button showing exactly what would be sent,
+including the `brother_ql` command line, so it can be run by hand on the host. A failed test print
+shows the printer's own words rather than a summary.
+
 **If the printer cannot be reached**, sign in still completes. The kiosk falls back to its own
 browser print dialog, and the failure is shown against the site in **Admin → Sites** with the
 reason. Admins can reprint any badge from the **On site** list.
@@ -271,9 +351,25 @@ HOST_PORT=8443
 HTTPS_PUBLIC_PORT=8443
 ```
 
-An address that isn't listed produces a browser warning. Change the list and restart; the
+An address that isn't listed produces a browser warning.
-certificate reissues itself automatically, and devices that already trust the authority accept
+
-it without any further work.
+After changing anything in `.env`, bring the container back with **`docker compose up -d`**, not
+`docker compose restart`. Restart reuses the running container along with the environment it
+started with, so the edit appears to do nothing; `up -d` recreates it and picks the new values
+up. Confirm with:
+
+```bash
+docker compose exec visitor-signin printenv HTTPS_HOSTNAMES
+docker compose logs --tail=20 visitor-signin | grep tls
+```
+
+The log should say `renewing the server certificate: HTTPS_HOSTNAMES changed` and then list every
+name it now covers. If it lists only `localhost`, `visitors.local` and a `172.x` address, the
+variable never reached the container — those are the defaults plus the container's own docker
+bridge address.
+
+Reissuing does **not** touch the certificate authority, so devices that already trust it keep
+working and no MDM profile needs redeploying.
 
 The kiosk is then at `https://visitors.local:8443`, admin at `https://visitors.local:8443/admin`.
 

package.json

@@ -7,7 +7,11 @@
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
-    "gen-secret": "node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\""
+    "version": "node scripts/version.mjs",
+    "gen-secret": "node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"",
+    "print-test": "node scripts/print-test.mjs",
+    "printer-status": "node scripts/printer-status.mjs",
+    "print-probe": "node scripts/print-probe.mjs"
   },
   "engines": {
     "node": ">=20"

public/css/admin.css

@@ -400,3 +400,48 @@ tr.row-bad td { background: #fdf0f2; }
   vertical-align: -2px;
   margin-right: 2px;
 }
+
+pre.raw {
+  margin: 0 0 14px;
+  padding: 12px;
+  background: var(--paper);
+  border: 1px solid var(--rule);
+  border-radius: 3px;
+  font-family: ui-monospace, Menlo, Consolas, monospace;
+  font-size: 12.5px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 320px;
+  overflow: auto;
+}
+
+/* The recommended download should not look identical to the two fallbacks. */
+.sys-actions .primary-link {
+  border-color: var(--deep);
+  background: var(--deep);
+  color: #fff;
+  font-weight: 600;
+}
+
+/* --------------------------------------------------- photo halftoning */
+
+.photo-tuning {
+  margin: 12px 0 16px;
+  padding: 14px;
+  border: 1px solid var(--rule);
+  border-radius: 3px;
+  background: var(--paper);
+}
+.photo-tuning input[type="range"] { width: 100%; }
+.photo-tuning .modal-field span b { font-variant-numeric: tabular-nums; }
+.photo-tuning .hint { margin: 10px 0; }
+
+.photo-preview {
+  display: block;
+  width: 100%;
+  margin-top: 12px;
+  border: 1px solid var(--rule);
+  border-radius: 3px;
+  background: #fff;
+}

public/js/admin.js

@@ -689,6 +689,7 @@ async function loadSites() {
             <button class="ghost" data-preview-badge="${s.id}">Preview badge</button>
             <button class="ghost" data-bitmap="${s.id}">Bitmap preview</button>
             ${s.printer.enabled ? `<button class="ghost" data-test-print="${s.id}">Test print</button>` : ''}
+            ${s.printer.enabled ? `<button class="ghost" data-print-diag="${s.id}">Diagnostics</button>` : ''}
           </div>
         </div>
         <dl class="site-meta">
@@ -702,9 +703,9 @@ async function loadSites() {
           <dt>Printer</dt>
           <dd>${
             s.printer.enabled && s.printer.host
-              ? `${esc(s.printer.model)} at ${esc(s.printer.host)}:${s.printer.port}${
+              ? `${esc(s.printer.model)} at ${esc(s.printer.host)}:${s.printer.port}, ${
-                  s.printer.rotate ? `, rotated ${s.printer.rotate}°` : ''
+                  s.printer.label === '62red' ? 'black and red roll' : 'black roll'
-                }${
+                }${s.printer.rotate ? `, rotated ${s.printer.rotate}°` : ''}${
                   s.printerStatus
                     ? s.printerStatus.ok
                       ? ` <span class="pill">last print ok, ${stamp(s.printerStatus.at)}</span>`
@@ -740,6 +741,17 @@ async function loadSites() {
       window.open(`/admin/api/sites/${btn.dataset.bitmap}/badge-bitmap`, '_blank')
     )
   );
+  $$('[data-print-diag]').forEach((btn) =>
+    btn.addEventListener('click', async () => {
+      const d = await api(`/sites/${btn.dataset.printDiag}/printer-diagnostics`);
+      openModal(
+        'Printer diagnostics',
+        `<pre class="raw">${esc(JSON.stringify(d, null, 2))}</pre>`,
+        null,
+        { saveLabel: 'Close', hideCancel: true }
+      );
+    })
+  );
   $$('[data-test-print]').forEach((btn) =>
     btn.addEventListener('click', async () => {
       btn.disabled = true;
@@ -748,7 +760,17 @@ async function loadSites() {
         await api(`/sites/${btn.dataset.testPrint}/test-print`, { method: 'POST' });
         toast('Sent to the printer.');
       } catch (err) {
-        toast(err.message, true);
+        // Show the printer's own words as well as the summary, because a refusal
+        // usually names the reason and the summary cannot cover every case.
+        const raw = err.payload?.raw;
+        openModal(
+          'The printer refused the job',
+          `<p>${esc(err.message)}</p>
+           ${err.payload?.command ? `<p class="hint">Command:</p><pre class="raw">${esc(err.payload.command)}</pre>` : ''}
+           ${raw ? `<p class="hint">What the printer and brother_ql said:</p><pre class="raw">${esc(raw)}</pre>` : ''}`,
+          null,
+          { saveLabel: 'Close', hideCancel: true }
+        );
       } finally {
         btn.disabled = false;
         btn.textContent = 'Test print';
@@ -764,16 +786,29 @@ async function loadSites() {
  * 62 mm is for a different printer.
  */
 const LABEL_PRESETS = [
-  { id: 'dk22205-90', label: 'Brother DK-22205 continuous, cut at 90 mm', w: 62, h: 90, photo: true },
+  { id: 'dk22205-90', label: 'Brother DK-22205 continuous, cut at 90 mm', w: 62, h: 90, photo: true, roll: '62' },
-  { id: 'dk11202', label: 'Brother DK-11202 die-cut 62 × 100 mm', w: 62, h: 100, photo: true },
+  { id: 'dk11202', label: 'Brother DK-11202 die-cut 62 × 100 mm', w: 62, h: 100, photo: true, roll: '62' },
-  { id: 'dk22251-90', label: 'Brother DK-22251 black/red continuous, cut at 90 mm', w: 62, h: 90, photo: true, accent: true },
+  { id: 'dk22251-90', label: 'Brother DK-22251 black/red continuous, cut at 90 mm', w: 62, h: 90, photo: true, roll: '62red', accent: true },
-  { id: 'dk11208', label: 'Brother DK-11208 die-cut 38 × 90 mm', w: 38, h: 90, photo: false },
+  { id: 'dk11208', label: 'Brother DK-11208 die-cut 38 × 90 mm', w: 38, h: 90, photo: false, roll: '62' },
-  { id: 'dk11209', label: 'Brother DK-11209 die-cut 29 × 62 mm', w: 29, h: 62, photo: false },
+  { id: 'dk11209', label: 'Brother DK-11209 die-cut 29 × 62 mm', w: 29, h: 62, photo: false, roll: '62' },
-  { id: 'dk11201', label: 'Brother DK-11201 die-cut 29 × 90 mm', w: 29, h: 90, photo: false },
+  { id: 'dk11201', label: 'Brother DK-11201 die-cut 29 × 90 mm', w: 29, h: 90, photo: false, roll: '62' },
-  { id: 'card', label: 'Card size 86 × 54 mm (not a QL-820NWB size)', w: 86, h: 54, photo: true },
+  { id: 'card', label: 'Card size 86 × 54 mm (not a QL-820NWB size)', w: 86, h: 54, photo: true, roll: '62' },
-  { id: 'dymo99014', label: 'Dymo 99014 101 × 54 mm', w: 101, h: 54, photo: true },
+  { id: 'dymo99014', label: 'Dymo 99014 101 × 54 mm', w: 101, h: 54, photo: true, roll: '62' },
 ];
 
+/**
+ * Which preset the saved settings correspond to. Dimensions alone are ambiguous —
+ * DK-22205 and DK-22251 are both 62 x 90 — so the roll type decides between them.
+ */
+function matchingPreset(site) {
+  return LABEL_PRESETS.find(
+    (p) =>
+      Number(site.badge.widthMm) === p.w &&
+      Number(site.badge.heightMm) === p.h &&
+      p.roll === (site.printer.label === '62red' ? '62red' : '62')
+  );
+}
+
 function openSiteModal(site) {
   openModal(
     `Edit ${site.name}`,
@@ -787,26 +822,53 @@ function openSiteModal(site) {
          <option value="">Custom size</option>
          ${LABEL_PRESETS.map(
            (p) =>
-             `<option value="${p.id}" ${
+             `<option value="${p.id}" ${matchingPreset(site)?.id === p.id ? 'selected' : ''}>${esc(p.label)}</option>`
-               Number(site.badge.widthMm) === p.w && Number(site.badge.heightMm) === p.h ? 'selected' : ''
-             }>${esc(p.label)}</option>`
          ).join('')}
        </select></label>
+     <p class="hint">A shortcut that fills in the boxes below. The size, the roll type and the
+     colour option are what actually get saved.</p>
      <div class="modal-row">
        ${field('Width (mm)', 'widthMm', site.badge.widthMm, 'number')}
        ${field('Height (mm)', 'heightMm', site.badge.heightMm, 'number')}
      </div>
      <p class="hint" id="badge-warning" hidden></p>
      <label class="inline"><input type="checkbox" name="showPhoto" id="badge-photo" ${site.badge.showPhoto ? 'checked' : ''}> Include the visitor's photo</label>
+     <div class="photo-tuning">
+       <label class="modal-field"><span>Photo rendering</span>
+         <select name="photoMode" id="photo-mode">
+           <option value="dither" ${site.photo.mode === 'dither' ? 'selected' : ''}>Error diffusion — best for faces</option>
+           <option value="threshold" ${site.photo.mode === 'threshold' ? 'selected' : ''}>Hard threshold — crisp, loses detail</option>
+           <option value="none" ${site.photo.mode === 'none' ? 'selected' : ''}>Leave it to the printer driver</option>
+         </select></label>
+       <label class="modal-field"><span>Threshold <b id="photo-threshold-value">${site.photo.threshold}</b>%</span>
+         <input type="range" name="photoThreshold" id="photo-threshold" min="5" max="95" step="5" value="${site.photo.threshold}"></label>
+       <label class="modal-field"><span>Contrast <b id="photo-contrast-value">${site.photo.contrast}</b></span>
+         <input type="range" name="photoContrast" id="photo-contrast" min="-50" max="100" step="10" value="${site.photo.contrast}"></label>
+       <button type="button" class="ghost" id="photo-preview-btn">Preview the photo settings</button>
+       <p class="hint">The printer has one bit per dot, so a photo has to become pure black and
+       white. A hard threshold turns a face into solid blocks; error diffusion scatters the
+       rounding error into neighbouring dots and keeps the tones readable. Higher threshold means
+       darker. The preview shows the most recent real visitor photo.</p>
+       <img id="photo-preview" class="photo-preview" alt="" hidden>
+     </div>
      <label class="inline"><input type="checkbox" name="accent" id="badge-accent" ${site.badge.accent ? 'checked' : ''}> Print the heading and the no-check warning in red</label>
-     <p class="hint">Red needs a two-colour roll such as the Brother DK-22251. On any other
+     <p class="hint" id="accent-note"></p>
-     roll it prints as grey. Two-colour printing is also much slower than black alone.</p>
+     <p class="hint">Two-colour printing is much slower than black alone.</p>
      <h4 class="modal-section">Printer</h4>
      <label class="inline"><input type="checkbox" name="printerEnabled" ${site.printer.enabled ? 'checked' : ''}> Print from the server, straight to a network printer</label>
      <div class="modal-row">
        ${field('Printer IP address', 'printerHost', site.printer.host, 'text')}
        ${field('Port', 'printerPort', site.printer.port, 'number')}
      </div>
+     <label class="modal-field"><span>Roll loaded in the printer</span>
+       <select name="printerLabel">
+         <option value="62" ${site.printer.label !== '62red' ? 'selected' : ''}>62 mm continuous, black only</option>
+         <option value="62red" ${site.printer.label === '62red' ? 'selected' : ''}>62 mm continuous, black and red (DK-22251)</option>
+       </select></label>
+     <p class="hint">This must match the roll actually in the machine, and it matters in both
+     directions. A two-colour job on a plain roll is refused as <em>Wrong Roll Type</em>; a
+     monochrome job on a DK-22251 is refused with <em>Black/Red on White paper is installed
+     now</em>. The DK-22251 needs the two-colour option even when the badge is entirely black.</p>
      <div class="modal-row">
        ${field('Model', 'printerModel', site.printer.model)}
        <label class="modal-field"><span>Rotation</span>
@@ -883,6 +945,12 @@ function openSiteModal(site) {
               port: Number(data.printerPort) || 9100,
               model: data.printerModel,
               rotate: Number(data.printerRotate) || 0,
+              label: data.printerLabel,
+            },
+            photo: {
+              mode: data.photoMode,
+              threshold: Number(data.photoThreshold),
+              contrast: Number(data.photoContrast),
             },
             branding: {
               brand: data.brand || null,
@@ -992,6 +1060,63 @@ function wireBannerEditor() {
   [pageInput, textInput].forEach((el) => el.addEventListener('input', showContrast));
   showContrast();
 
+  // Live readouts for the halftone sliders, and a preview on demand. The preview
+  // is not automatic: it re-renders a real photo five times and is not free.
+  const modeSel = $('#photo-mode');
+  const thr = $('#photo-threshold');
+  const con = $('#photo-contrast');
+  const refreshLabels = () => {
+    $('#photo-threshold-value').textContent = thr.value;
+    $('#photo-contrast-value').textContent = con.value;
+    const off = modeSel.value === 'none';
+    thr.disabled = off;
+    con.disabled = off;
+  };
+  [thr, con].forEach((el) => el?.addEventListener('input', refreshLabels));
+  modeSel?.addEventListener('change', refreshLabels);
+  refreshLabels();
+
+  $('#photo-preview-btn')?.addEventListener('click', () => {
+    const img = $('#photo-preview');
+    const params = new URLSearchParams({
+      mode: modeSel.value,
+      threshold: thr.value,
+      contrast: con.value,
+      t: Date.now(),
+    });
+    img.src = `/admin/api/sites/${site.id}/photo-preview?${params}`;
+    img.hidden = false;
+  });
+
+  // Red is only possible on the two-colour roll, so say so as the two settings change.
+  const accentBox = $('#badge-accent');
+  const rollSelect = $('#modal-form [name="printerLabel"]');
+  const accentNote = $('#accent-note');
+
+  const showAccentNote = () => {
+    if (!accentNote) return;
+    if (!accentBox?.checked) {
+      accentNote.hidden = false;
+      accentNote.className = 'hint';
+      accentNote.textContent = 'Everything prints black.';
+      return;
+    }
+    if (rollSelect?.value === '62red') {
+      accentNote.hidden = false;
+      accentNote.className = 'hint';
+      accentNote.textContent = 'The heading and the no-check warning will print red.';
+    } else {
+      accentNote.hidden = false;
+      accentNote.className = 'hint warn';
+      accentNote.textContent =
+        'The roll selected below cannot print red, so these will come out black. Load a DK-22251 and change the roll setting to use colour.';
+    }
+  };
+
+  accentBox?.addEventListener('change', showAccentNote);
+  rollSelect?.addEventListener('change', showAccentNote);
+  showAccentNote();
+
   $('#banner-file').addEventListener('change', (event) => {
     const file = event.target.files[0];
     if (!file) return;
@@ -1046,6 +1171,14 @@ function wireBadgePreset() {
     height.value = preset.h;
     $('#badge-photo').checked = preset.photo;
     $('#badge-accent').checked = Boolean(preset.accent);
+    // The preset knows which roll it describes, so keep the two in step. Picking
+    // the DK-22251 preset while the roll stayed on "black only" is what makes the
+    // printer refuse the job.
+    const roll = $('#modal-form [name="printerLabel"]');
+    if (roll && preset.roll) {
+      roll.value = preset.roll;
+      roll.dispatchEvent(new Event('change'));
+    }
     check();
   });
 
@@ -1354,7 +1487,9 @@ function renderTls(tls) {
       itself before it lapses, and devices that trust the authority keep working without being
       touched again.</p>
     <div class="sys-actions">
-      <a class="ghost" href="/admin/api/tls/ca.crt" download>Download the CA certificate</a>
+      <a class="ghost primary-link" href="/admin/api/tls/ca-bundle.zip" download>Download all certificates (.zip)</a>
+      <a class="ghost" href="/admin/api/tls/ca.crt" download>.crt only</a>
+      <a class="ghost" href="/admin/api/tls/ca.cer" download>.cer only</a>
       <button class="ghost owner-only" id="renew-cert">Renew the server certificate</button>
       <button class="ghost danger owner-only" id="new-ca">Start a new authority</button>
     </div>`;

push-to-gitea.ps1

@@ -7,15 +7,10 @@
 
 $Remote = 'https://gitea.hideawaygaming.com.au/jessikitty/visitor-signin.git'
 
-# git reports failure through its exit code, not as a PowerShell error, so every
+# git is called directly and $LASTEXITCODE checked straight afterwards. Wrapping
-# call has to be checked. Without this the script reports success after a
+# it in a function does not work: a PowerShell function returns everything written
-# rejected push, which is exactly what it used to do.
+# to the output stream, so the caller receives git's console output as well as the
-function Invoke-Git {
+# exit code, and comparing that array against 0 reports failure every time.
-    param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Arguments)
-    & git @Arguments
-    return $LASTEXITCODE
-}
-
 function Fail($message) {
     Write-Host ''
     Write-Host $message -ForegroundColor Red
@@ -27,62 +22,89 @@ if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
     Fail 'Git is not installed or not on PATH. Get it from https://git-scm.com/download/win'
 }
 
-# Keeps line endings sane between Windows and the Ubuntu docker host.
 git config --global core.autocrlf input | Out-Null
 
+# git refuses to commit without an identity, and says so in a way that is easy to
+# miss among its other output.
+$who = git config user.email
+if (-not $who) { $who = git config --global user.email }
+if (-not $who) {
+    Write-Host 'Git does not know who you are. Set that once:' -ForegroundColor Yellow
+    Write-Host '    git config --global user.email "you@example.com"'
+    Write-Host '    git config --global user.name "Your Name"'
+    Fail 'Nothing was committed.'
+}
+
 if (-not (Test-Path '.git')) {
     Write-Host 'Setting up a new local repository...'
-    if ((Invoke-Git init -b main) -ne 0) { Fail 'git init failed.' }
+    git init -b main
+    if ($LASTEXITCODE -ne 0) { Fail 'git init failed.' }
 }
 
-if ((git remote) -match '^origin$') {
+if ((git remote) -match '^origin$') { git remote set-url origin $Remote }
-    git remote set-url origin $Remote
+else { git remote add origin $Remote }
-} else {
+
-    git remote add origin $Remote
+# Whatever branch is checked out, not a hard-coded one. Pushing 'main' while the
+# work sits on 'deploy' reports "Everything up-to-date" and sends nothing.
+$branch = (git rev-parse --abbrev-ref HEAD).Trim()
+if (-not $branch -or $branch -eq 'HEAD') { Fail 'No branch is checked out here.' }
+Write-Host "Branch: $branch" -ForegroundColor Cyan
+
+# ------------------------------------------- an unfinished rebase blocks everything
+
+$gitDir = git rev-parse --git-dir 2>$null
+if ($gitDir) {
+    $stuck = @('rebase-merge', 'rebase-apply', 'MERGE_HEAD', 'CHERRY_PICK_HEAD') |
+        Where-Object { Test-Path (Join-Path $gitDir $_) }
+    if ($stuck) {
+        Write-Host ''
+        Write-Host 'There is an unfinished rebase or merge here.' -ForegroundColor Red
+        Write-Host '  git rebase --abort      throw it away, back to how things were'
+        Write-Host '  git status              see which files need attention'
+        Write-Host '  git rebase --continue   after fixing those files'
+        Fail 'Nothing was done.'
+    }
 }
 
 # ---------------------------------------------------------------- commit
 
 git add -A
-$pending = git status --porcelain
+if (git status --porcelain) {
-if ($pending) {
     $message = Read-Host 'Describe this change (press enter for a dated default)'
     if (-not $message) { $message = "Update $(Get-Date -Format 'yyyy-MM-dd HH:mm')" }
-    if ((Invoke-Git commit -m $message) -ne 0) { Fail 'git commit failed.' }
+    git commit -m $message
+    if ($LASTEXITCODE -ne 0) { Fail 'git commit failed. The message above says why.' }
     Write-Host 'Committed.' -ForegroundColor Green
 } else {
-    Write-Host 'No file changes to commit. Checking for anything unpushed...' -ForegroundColor Yellow
+    Write-Host 'Nothing new to commit.' -ForegroundColor Yellow
 }
 
 # ------------------------------------------------------- catch up, then push
 
-Write-Host 'Checking what is on the server...'
+git fetch origin
-if ((Invoke-Git fetch origin) -ne 0) {
+if ($LASTEXITCODE -ne 0) { Fail 'Could not reach Gitea. Check the network and your sign in details.' }
-    Fail 'Could not reach Gitea. Check the network and your sign in details.'
-}
 
-if (git ls-remote --heads origin main) {
+if (git ls-remote --heads origin $branch) {
-    $behind = (git rev-list --count HEAD..origin/main 2>$null)
+    $behind = git rev-list --count "HEAD..origin/$branch" 2>$null
     if ($behind -and [int]$behind -gt 0) {
         Write-Host "The server has $behind commit(s) this folder does not. Replaying your work on top..."
-        if ((Invoke-Git pull --rebase origin main) -ne 0) {
+        git pull --rebase origin $branch
+        if ($LASTEXITCODE -ne 0) {
             Write-Host ''
             Write-Host 'The two histories could not be joined automatically.' -ForegroundColor Red
-            Write-Host ''
+            Write-Host "  git log --oneline HEAD..origin/$branch      what is on the server"
-            Write-Host 'See what is on the server that you do not have:' -ForegroundColor Yellow
+            Write-Host "  git push --force-with-lease origin $branch  if this folder is the good copy"
-            Write-Host '    git log --oneline HEAD..origin/main'
+            Fail 'Nothing was sent.'
-            Write-Host ''
-            Write-Host 'If that is nothing you need, and this folder is the good copy:' -ForegroundColor Yellow
-            Write-Host '    git push --force-with-lease origin main'
-            exit 1
         }
     }
+} else {
+    Write-Host "Branch '$branch' is not on the server yet; it will be created."
 }
 
-if ((Invoke-Git push -u origin main) -ne 0) {
+git push -u origin $branch
-    Fail 'The push was rejected. Read the message above. Nothing was sent.'
+if ($LASTEXITCODE -ne 0) { Fail 'The push was rejected. The message above says why. Nothing was sent.' }
-}
 
 Write-Host ''
-Write-Host 'Pushed successfully.' -ForegroundColor Green
+Write-Host "Pushed $branch successfully." -ForegroundColor Green
+git log --oneline -1
 Write-Host 'https://gitea.hideawaygaming.com.au/jessikitty/visitor-signin'

push-to-gitea.sh

@@ -11,6 +11,15 @@ command -v git >/dev/null || fail "Git is not installed."
 
 git config --global core.autocrlf input >/dev/null 2>&1 || true
 
+if [ -z "$(git config user.email || git config --global user.email)" ]; then
+  cat >&2 <<'MSG'
+Git does not know who you are. Set that once:
+    git config --global user.email "you@example.com"
+    git config --global user.name  "Your Name"
+MSG
+  exit 1
+fi
+
 [ -d .git ] || git init -b main || fail "git init failed."
 
 if git remote | grep -qx origin; then
@@ -19,6 +28,31 @@ else
   git remote add origin "$REMOTE"
 fi
 
+# Whatever branch is checked out, not a hard-coded one.
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+[ -n "$BRANCH" ] && [ "$BRANCH" != "HEAD" ] || fail "No branch is checked out here."
+echo "Branch: $BRANCH"
+
+# An unfinished rebase or merge blocks everything below, and git's own error is
+# easy to mistake for a push problem.
+GIT_DIR_PATH=$(git rev-parse --git-dir 2>/dev/null || echo .git)
+for marker in rebase-merge rebase-apply MERGE_HEAD CHERRY_PICK_HEAD; do
+  if [ -e "$GIT_DIR_PATH/$marker" ]; then
+    cat >&2 <<'MSG'
+
+There is an unfinished rebase or merge in this folder.
+Nothing else can happen until it is settled:
+
+  git rebase --abort      throw the attempt away, back to how things were
+  git status              see which files still need attention
+  git rebase --continue   after fixing the files git listed
+
+If unsure, "git rebase --abort" is the safe one.
+MSG
+    exit 1
+  fi
+done
+
 git add -A
 if [ -n "$(git status --porcelain)" ]; then
   read -r -p "Describe this change (enter for a dated default): " MSG
@@ -31,28 +65,29 @@ fi
 
 git fetch origin || fail "Could not reach Gitea."
 
-if git ls-remote --heads origin main | grep -q main; then
+if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
-  BEHIND=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo 0)
+  BEHIND=$(git rev-list --count "HEAD..origin/$BRANCH" 2>/dev/null || echo 0)
   if [ "$BEHIND" -gt 0 ]; then
     echo "The server has $BEHIND commit(s) this folder does not. Replaying your work on top..."
-    if ! git pull --rebase origin main; then
+    if ! git pull --rebase origin "$BRANCH"; then
       cat >&2 <<'MSG'
 
 The two histories could not be joined automatically.
 
 See what is on the server that you do not have:
-    git log --oneline HEAD..origin/main
+    git log --oneline HEAD..origin/$BRANCH
 
 If that is nothing you need, and this folder is the good copy:
-    git push --force-with-lease origin main
+    git push --force-with-lease origin $BRANCH
 MSG
       exit 1
     fi
   fi
 fi
 
-git push -u origin main || fail "The push was rejected. Read the message above. Nothing was sent."
+git push -u origin "$BRANCH" || fail "The push was rejected. Read the message above. Nothing was sent."
 
 echo
-echo "Pushed successfully."
+echo "Pushed $BRANCH successfully."
+git log --oneline -1
 echo "https://gitea.hideawaygaming.com.au/jessikitty/visitor-signin"

scripts/gen-cert.sh

@@ -25,8 +25,10 @@ fi
 
 if docker compose ps --status running 2>/dev/null | grep -q visitor-signin; then
   docker compose exec -T visitor-signin node scripts/make-cert.mjs $FORCE
-  echo "Restarting so the new certificate is served..."
+  echo "Recreating the container so the new certificate is served..."
-  docker compose restart visitor-signin
+  # up -d rather than restart: restart keeps the environment the container was
+  # started with, so an edited .env would be ignored.
+  docker compose up -d visitor-signin
 else
   node scripts/make-cert.mjs $FORCE
 fi

scripts/print-probe.mjs

@@ -0,0 +1,100 @@
+/**
+ * Tries roll ids one at a time, waiting for you to say what came out.
+ *
+ *   docker compose exec -it visitor-signin node scripts/print-probe.mjs
+ *
+ * Note the -it: this asks questions, so the container needs a terminal attached.
+ *
+ * Start with printer-status.mjs — if the printer answers, it tells you the right
+ * id outright and this is unnecessary. Use this when the printer will not report
+ * its status, or when it does and the job is still refused.
+ */
+import fs from 'node:fs';
+import readline from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
+import db from '../src/db.js';
+import config from '../src/config.js';
+import * as printer from '../src/printer.js';
+
+// Ordered by how likely each is on a 62 mm machine, cheapest guesses first.
+const CANDIDATES = [
+  ['62', '62 mm continuous, black only'],
+  ['62x100', '62 x 100 mm die-cut'],
+  ['62red', '62 mm continuous, black and red (DK-22251)'],
+  ['62x29', '62 x 29 mm die-cut'],
+  ['29', '29 mm continuous'],
+  ['29x90', '29 x 90 mm die-cut'],
+  ['38', '38 mm continuous'],
+  ['50', '50 mm continuous'],
+  ['54', '54 mm continuous'],
+];
+
+const site = db
+  .prepare('SELECT * FROM sites WHERE printer_host IS NOT NULL ORDER BY id LIMIT 1')
+  .get();
+
+if (!site) {
+  console.error('No site has a printer address set.');
+  process.exit(1);
+}
+
+const target = `tcp://${site.printer_host}:${site.printer_port || 9100}`;
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+console.log(`\n  Printer: ${site.printer_model || 'QL-820NWB'} at ${target}`);
+console.log('  One label will be sent per attempt. After each, say whether anything came out.');
+console.log('  Press Ctrl+C at any point to stop.\n');
+
+const results = [];
+
+for (const [label, description] of CANDIDATES) {
+  const answer = (await rl.question(`  Try "${label}" (${description})? [Y/n/q] `)).trim().toLowerCase();
+  if (answer === 'q') break;
+  if (answer === 'n') {
+    results.push([label, 'skipped']);
+    continue;
+  }
+
+  const png = await printer.renderBadgePng(printer.sampleVisit(site), { ...site, printer_label: label });
+  const file = '/tmp/probe.png';
+  fs.writeFileSync(file, png);
+
+  let sent = true;
+  let detail = '';
+  try {
+    execFileSync(
+      config.printing.command,
+      [
+        '--backend', 'network',
+        '--model', site.printer_model || 'QL-820NWB',
+        '--printer', target,
+        'print', '--label', label, ...(label === '62red' ? ['--red'] : []), file,
+      ],
+      { stdio: ['ignore', 'pipe', 'pipe'], timeout: config.printing.timeoutMs }
+    );
+  } catch (err) {
+    sent = false;
+    detail = `${err.stdout || ''}${err.stderr || ''}`.trim().split('\n').pop() || err.message;
+  }
+
+  if (!sent) {
+    console.log(`     could not send: ${detail}\n`);
+    results.push([label, `send failed: ${detail}`]);
+    continue;
+  }
+
+  const came = (await rl.question('     Did a label print? [y/N] ')).trim().toLowerCase();
+  if (came === 'y') {
+    results.push([label, 'PRINTED']);
+    console.log(`\n  That is the one. Set "Roll loaded in the printer" so it sends ${label}.\n`);
+    break;
+  }
+  results.push([label, 'nothing came out']);
+  console.log('     Clear the error on the printer (open and close the cover) before the next try.\n');
+}
+
+rl.close();
+
+console.log('  Summary');
+for (const [label, outcome] of results) console.log(`    ${label.padEnd(8)} ${outcome}`);
+console.log('');

scripts/print-test.mjs

@@ -0,0 +1,107 @@
+/**
+ * Renders a badge and prints it, showing everything on the way through.
+ *
+ * For working out why a printer will not accept a job, without going through the
+ * kiosk or the admin console. Run inside the container:
+ *
+ *   docker compose exec visitor-signin node scripts/print-test.mjs
+ *   docker compose exec visitor-signin node scripts/print-test.mjs --label 62x100
+ *   docker compose exec visitor-signin node scripts/print-test.mjs --dry
+ *
+ * Options:
+ *   --site N       which site to use (default: the first one)
+ *   --label ID     override the roll id sent to the printer, without saving it
+ *   --rotate DEG   override the rotation, without saving it
+ *   --dry          render only, do not print
+ */
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import db from '../src/db.js';
+import config from '../src/config.js';
+import * as printer from '../src/printer.js';
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')
+    ? process.argv[i + 1]
+    : fallback;
+}
+const has = (name) => process.argv.includes(`--${name}`);
+
+const siteId = Number(arg('site', 0));
+const site = siteId
+  ? db.prepare('SELECT * FROM sites WHERE id = ?').get(siteId)
+  : db.prepare('SELECT * FROM sites ORDER BY id LIMIT 1').get();
+
+if (!site) {
+  console.error('No sites exist yet.');
+  process.exit(1);
+}
+
+if (arg('label')) site.printer_label = arg('label');
+if (arg('rotate')) site.printer_rotate = Number(arg('rotate'));
+
+const label = printer.labelFor(site);
+const target = `tcp://${site.printer_host}:${site.printer_port || 9100}`;
+
+console.log('');
+console.log(`  site            ${site.name}`);
+console.log(`  printer         ${site.printer_model || 'QL-820NWB'} at ${target}`);
+console.log(`  server printing ${site.printer_enabled ? 'on' : 'OFF — the kiosk would print instead'}`);
+console.log(`  badge           ${site.badge_width_mm} x ${site.badge_height_mm} mm, rotate ${site.printer_rotate || 0}`);
+console.log(`  roll setting    ${site.printer_label || '(unset)'}  ->  --label ${label}`);
+console.log(`  red             requested ${Boolean(site.badge_accent)}, will print ${printer.accentWillPrintRed(site)}`);
+
+const png = await printer.renderBadgePng(printer.sampleVisit(site), site);
+const file = '/tmp/print-test.png';
+fs.writeFileSync(file, png);
+console.log(`  rendered        ${png.readUInt32BE(16)} x ${png.readUInt32BE(20)} dots -> ${file}`);
+
+if (!site.printer_host) {
+  console.error('\n  No printer address set for this site. Set one in Admin -> Sites -> Edit.');
+  process.exit(1);
+}
+
+if (has('dry')) {
+  console.log('\n  --dry given, so nothing was sent.\n');
+  process.exit(0);
+}
+
+const args = [
+  '--backend', 'network',
+  '--model', site.printer_model || 'QL-820NWB',
+  '--printer', target,
+  'print',
+  '--label', label,
+];
+// Required on black/red tape even when the badge is entirely black.
+if (label === '62red') args.push('--red');
+args.push(file);
+
+console.log('');
+console.log(`  running: ${config.printing.command} ${args.join(' ')}`);
+console.log('');
+
+try {
+  const out = execFileSync(config.printing.command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: config.printing.timeoutMs,
+  });
+  console.log(out.trim() || '  (no output)');
+  console.log('\n  Sent. If nothing came out, the printer rejected it silently — check its display.\n');
+} catch (err) {
+  console.error('  FAILED\n');
+  console.error(`${err.stdout || ''}${err.stderr || ''}`.trim() || err.message);
+  console.error('');
+  console.error('  Roll ids this printer understands:');
+  console.error('    62       62 mm continuous, black only');
+  console.error('    62red    62 mm continuous, black and red (DK-22251)');
+  console.error('    62x100   62 x 100 mm DIE-CUT (pre-cut labels, not a continuous roll)');
+  console.error('    62x29    62 x 29 mm die-cut');
+  console.error('');
+  console.error('  A continuous roll sent a die-cut id, or the reverse, is refused as a wrong roll.');
+  console.error('  Try:  node scripts/print-test.mjs --label 62x100');
+  console.error('');
+  process.exit(1);
+}

scripts/printer-status.mjs

@@ -0,0 +1,172 @@
+/**
+ * Asks the printer what it actually has loaded, and what it is complaining about.
+ *
+ *   docker compose exec visitor-signin node scripts/printer-status.mjs
+ *   docker compose exec visitor-signin node scripts/printer-status.mjs --host 10.0.0.5
+ *
+ * brother_ql's network backend only writes to the socket; it never reads, which is
+ * why a refused job still looks like a success. The Brother raster protocol has a
+ * status request that returns a 32 byte block describing the media in the machine
+ * and any error, so we ask directly.
+ */
+import net from 'node:net';
+import db from '../src/db.js';
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')
+    ? process.argv[i + 1]
+    : fallback;
+}
+
+const site = arg('site')
+  ? db.prepare('SELECT * FROM sites WHERE id = ?').get(Number(arg('site')))
+  : db.prepare('SELECT * FROM sites WHERE printer_host IS NOT NULL ORDER BY id LIMIT 1').get();
+
+const host = arg('host', site?.printer_host);
+const port = Number(arg('port', site?.printer_port || 9100));
+
+if (!host) {
+  console.error('No printer address. Set one in Admin -> Sites, or pass --host.');
+  process.exit(1);
+}
+
+/* ------------------------------------------------------------- decoding */
+
+const MEDIA_TYPES = {
+  0x00: 'no media loaded',
+  0x0a: 'continuous roll',
+  0x0b: 'die-cut labels',
+  0x4a: 'continuous roll (cleaning)',
+  0x4b: 'die-cut labels (cleaning)',
+};
+
+const ERRORS_1 = [
+  [0x01, 'no media loaded'],
+  [0x02, 'end of media'],
+  [0x04, 'cutter jam'],
+  [0x08, 'weak batteries'],
+  [0x10, 'printer in use'],
+  [0x80, 'printer turned off'],
+];
+
+const ERRORS_2 = [
+  [0x01, 'wrong media — the job does not match the roll that is loaded'],
+  [0x04, 'expansion buffer full'],
+  [0x08, 'communication error'],
+  [0x10, 'communication buffer full'],
+  [0x20, 'cover is open'],
+  [0x40, 'cancel key pressed'],
+  [0x80, 'media cannot be fed'],
+];
+
+function decode(buf) {
+  if (buf.length < 32) return { error: `Short reply (${buf.length} bytes).` };
+  const mediaWidth = buf[10];
+  const mediaType = buf[11];
+  const mediaLength = buf[17];
+  return {
+    mediaWidthMm: mediaWidth,
+    mediaLengthMm: mediaLength,
+    mediaType: MEDIA_TYPES[mediaType] || `unknown (0x${mediaType.toString(16)})`,
+    mediaTypeRaw: mediaType,
+    errors: [
+      ...ERRORS_1.filter(([bit]) => buf[8] & bit).map(([, text]) => text),
+      ...ERRORS_2.filter(([bit]) => buf[9] & bit).map(([, text]) => text),
+    ],
+    raw: buf.subarray(0, 32).toString('hex').replace(/(..)/g, '$1 ').trim(),
+  };
+}
+
+/** The label id brother_ql should be given, worked out from what is loaded. */
+function suggestLabel(status) {
+  if (status.mediaTypeRaw === 0x00) return null;
+  const continuous = status.mediaTypeRaw === 0x0a || status.mediaTypeRaw === 0x4a;
+  if (continuous) {
+    return String(status.mediaWidthMm); // 62, 29, 12 ...
+  }
+  return status.mediaLengthMm
+    ? `${status.mediaWidthMm}x${status.mediaLengthMm}`
+    : `${status.mediaWidthMm} (die-cut, length unknown)`;
+}
+
+/* --------------------------------------------------------------- asking */
+
+console.log(`\n  Asking ${host}:${port} what it has loaded...\n`);
+
+const socket = net.createConnection({ host, port, timeout: 8000 });
+const chunks = [];
+
+socket.on('connect', () => {
+  // 200 null bytes clears any half-finished job, then initialise, then ask.
+  socket.write(Buffer.alloc(200, 0x00));
+  socket.write(Buffer.from([0x1b, 0x40]));
+  socket.write(Buffer.from([0x1b, 0x69, 0x53]));
+
+  // Some firmware only answers once it is in raster mode, so ask again that way
+  // before giving up.
+  setTimeout(() => {
+    if (!chunks.length && !socket.destroyed) {
+      socket.write(Buffer.from([0x1b, 0x69, 0x61, 0x01]));
+      socket.write(Buffer.from([0x1b, 0x69, 0x53]));
+    }
+  }, 1500);
+});
+
+socket.on('data', (d) => {
+  chunks.push(d);
+  if (Buffer.concat(chunks).length >= 32) socket.end();
+});
+
+socket.on('timeout', () => {
+  socket.destroy();
+  if (!chunks.length) {
+    console.error('  The printer accepted the connection but sent nothing back.');
+    console.error('');
+    console.error('  Many Brother network print servers are write-only on port 9100: they accept');
+    console.error('  jobs but never report status, even though the same printer answers happily');
+    console.error('  over USB. If this is one of them, no amount of asking will help.');
+    console.error('');
+    console.error('  Read the printer instead from:');
+    console.error('    - the display on the machine itself');
+    console.error('    - Brother Status Monitor, on a PC with the printer installed');
+    console.error('    - the printer\'s own web page, at http://' + host + '/');
+    console.error('');
+    console.error('  Status Monitor in particular gives the exact reason a job was refused,');
+    console.error('  which is more than brother_ql can tell you — its network backend never');
+    console.error('  reads the socket, so it reports success whatever the printer does.');
+    console.error('');
+    process.exit(1);
+  }
+});
+
+socket.on('error', (err) => {
+  console.error(`  Could not reach it: ${err.message}\n`);
+  process.exit(1);
+});
+
+socket.on('close', () => {
+  const buf = Buffer.concat(chunks);
+  if (!buf.length) process.exit(1);
+
+  const status = decode(buf);
+  if (status.error) {
+    console.error(`  ${status.error}\n  raw: ${buf.toString('hex')}\n`);
+    process.exit(1);
+  }
+
+  console.log(`  media loaded    ${status.mediaWidthMm} mm ${status.mediaType}`);
+  if (status.mediaLengthMm) console.log(`  label length    ${status.mediaLengthMm} mm`);
+  console.log(`  errors          ${status.errors.length ? status.errors.join('; ') : 'none reported'}`);
+  console.log(`  raw status      ${status.raw}`);
+
+  const suggested = suggestLabel(status);
+  console.log('');
+  if (!suggested) {
+    console.log('  No media detected. Open and close the cover to make it re-read the roll.');
+  } else {
+    console.log(`  Use this roll id:  --label ${suggested}`);
+    console.log(`  Try it with:       node scripts/print-test.mjs --label ${suggested}`);
+  }
+  console.log('');
+});

scripts/version.mjs

@@ -0,0 +1,32 @@
+// Reports what this container is actually running, so an upgrade that did not
+// land can be spotted without guesswork.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(here, '..');
+
+const FEATURES = [
+  ['server-side printing', 'src/printer.js', null],
+  ['roll type is a separate setting', 'src/routes/admin.js', 'printer_label'],
+  ['roll type in the console', 'public/js/admin.js', 'printerLabel'],
+  ['company field', 'src/routes/kiosk.js', 'company'],
+  ['separate login page', 'public/login.html', 'step-password'],
+  ['per-site branding', 'src/branding.js', null],
+  ['CA in DER form for Jamf', 'src/tls.js', 'caCertificateDer'],
+];
+
+console.log('');
+for (const [name, file, needle] of FEATURES) {
+  const full = path.join(root, file);
+  let state = 'MISSING';
+  if (fs.existsSync(full)) {
+    state = !needle || fs.readFileSync(full, 'utf8').includes(needle) ? 'present' : 'OLD VERSION';
+  }
+  console.log(`  ${state.padEnd(12)} ${name}`);
+}
+console.log('');
+console.log('Anything not "present" means this container is running older code.');
+console.log('On the docker host:  git pull && docker compose up -d --build');
+console.log('');

src/db.js

@@ -27,6 +27,10 @@ CREATE TABLE IF NOT EXISTS sites (
   printer_port  INTEGER NOT NULL DEFAULT 9100,
   printer_model TEXT NOT NULL DEFAULT 'QL-820NWB',
   printer_rotate INTEGER NOT NULL DEFAULT 0,
+  printer_label TEXT NOT NULL DEFAULT '62',
+  photo_mode    TEXT NOT NULL DEFAULT 'dither',
+  photo_threshold INTEGER NOT NULL DEFAULT 50,
+  photo_contrast  INTEGER NOT NULL DEFAULT 20,
   banner_path   TEXT,
   banner_height INTEGER NOT NULL DEFAULT 64,
   banner_align  TEXT NOT NULL DEFAULT 'left',
@@ -183,6 +187,15 @@ addColumn('sites', 'printer_host', 'TEXT');
 addColumn('sites', 'printer_port', 'INTEGER NOT NULL DEFAULT 9100');
 addColumn('sites', 'printer_model', "TEXT NOT NULL DEFAULT 'QL-820NWB'");
 addColumn('sites', 'printer_rotate', 'INTEGER NOT NULL DEFAULT 0');
+// Which roll is physically loaded. Kept separate from the red styling option:
+// the printer refuses a two-colour job on a plain roll, so guessing the media
+// from a design setting means a wrong-roll error nobody can explain.
+addColumn('sites', 'printer_label', "TEXT NOT NULL DEFAULT '62'");
+// How the photo is reduced to the printer's one bit per dot. A plain threshold
+// turns a face into solid blocks; error diffusion keeps the tones readable.
+addColumn('sites', 'photo_mode', "TEXT NOT NULL DEFAULT 'dither'");
+addColumn('sites', 'photo_threshold', 'INTEGER NOT NULL DEFAULT 50');
+addColumn('sites', 'photo_contrast', 'INTEGER NOT NULL DEFAULT 20');
 addColumn('frequent_visitors', 'company', 'TEXT');
 
 db.exec('CREATE INDEX IF NOT EXISTS idx_visits_site ON visits(site_id, signed_out_at)');

src/printer.js

@@ -41,9 +41,175 @@ export function isConfigured(site) {
   return Boolean(site?.printer_enabled && site?.printer_host);
 }
 
-/** brother_ql's label id. The two-colour roll is a different label to the plain one. */
+/**
+ * brother_ql's media id for the roll that is actually loaded.
+ *
+ * This is set explicitly rather than inferred from the red styling option. A
+ * two-colour job sent to a plain roll is rejected by the printer with "Wrong
+ * Roll Type", which gives no clue that a colour checkbox caused it.
+ */
+export const ROLL_TYPES = {
+  '62': '62 mm continuous, black only',
+  '62red': '62 mm continuous, black and red (DK-22251)',
+};
+
 export function labelFor(site) {
-  return site?.badge_accent ? '62red' : '62';
+  const label = site?.printer_label;
+  return Object.hasOwn(ROLL_TYPES, label) ? label : '62';
+}
+
+/** Red ink only exists on the two-colour roll; anywhere else it prints dark grey. */
+export function accentWillPrintRed(site) {
+  return Boolean(site?.badge_accent) && labelFor(site) === '62red';
+}
+
+/* ------------------------------------------------- photo halftoning */
+
+export const PHOTO_MODES = {
+  dither: 'Error diffusion — best for faces',
+  threshold: 'Hard threshold — crisp, loses detail',
+  none: 'Leave it to the printer driver',
+};
+
+/**
+ * Reduces a photo to the one bit per dot the printer actually has.
+ *
+ * Done here rather than left to brother_ql so the preview and the label agree,
+ * and because the default is a plain threshold: every pixel darker than the cut
+ * becomes solid black, which turns a face into a few featureless blobs. Error
+ * diffusion spreads the rounding error into neighbouring pixels instead, so mid
+ * tones survive as a pattern of dots.
+ */
+function halftone(ctx, x, y, size, { mode = 'dither', threshold = 50, contrast = 20 } = {}) {
+  if (mode === 'none') return;
+
+  const image = ctx.getImageData(x, y, size, size);
+  const { data, width, height } = image;
+  const cut = Math.max(1, Math.min(99, threshold)) * 2.55;
+
+  // Standard contrast curve, pivoting on mid grey. Webcam photos are flat and
+  // flatten further when reduced to two tones, so a little lift helps.
+  const c = Math.max(-100, Math.min(100, contrast));
+  const factor = (259 * (c + 255)) / (255 * (259 - c));
+
+  // Greyscale first, into a float buffer so the diffused error does not clip.
+  const grey = new Float32Array(width * height);
+  for (let i = 0; i < width * height; i += 1) {
+    const r = data[i * 4];
+    const g = data[i * 4 + 1];
+    const b = data[i * 4 + 2];
+    const luma = 0.299 * r + 0.587 * g + 0.114 * b;
+    grey[i] = Math.max(0, Math.min(255, factor * (luma - 128) + 128));
+  }
+
+  for (let py = 0; py < height; py += 1) {
+    for (let px = 0; px < width; px += 1) {
+      const i = py * width + px;
+      const old = grey[i];
+      const next = old < cut ? 0 : 255;
+      grey[i] = next;
+
+      if (mode === 'dither') {
+        // Floyd-Steinberg: push the rounding error to pixels not yet visited.
+        const err = old - next;
+        const spread = (dx, dy, weight) => {
+          const nx = px + dx;
+          const ny = py + dy;
+          if (nx < 0 || nx >= width || ny >= height) return;
+          grey[ny * width + nx] += err * weight;
+        };
+        spread(1, 0, 7 / 16);
+        spread(-1, 1, 3 / 16);
+        spread(0, 1, 5 / 16);
+        spread(1, 1, 1 / 16);
+      }
+    }
+  }
+
+  for (let i = 0; i < width * height; i += 1) {
+    const v = grey[i] < 128 ? 0 : 255;
+    data[i * 4] = v;
+    data[i * 4 + 1] = v;
+    data[i * 4 + 2] = v;
+    data[i * 4 + 3] = 255;
+  }
+  ctx.putImageData(image, x, y);
+}
+
+export function photoSettings(site) {
+  return {
+    mode: Object.hasOwn(PHOTO_MODES, site?.photo_mode) ? site.photo_mode : 'dither',
+    threshold: Number.isFinite(Number(site?.photo_threshold)) ? Number(site.photo_threshold) : 50,
+    contrast: Number.isFinite(Number(site?.photo_contrast)) ? Number(site.photo_contrast) : 20,
+  };
+}
+
+/**
+ * A comparison sheet: the same photo at several settings, side by side, so the
+ * right one can be chosen by eye rather than by guessing at numbers.
+ */
+export async function photoPreviewPng(photoPath, current = {}) {
+  const tile = 260;
+  const gap = 18;
+  const caption = 46;
+
+  const settings = photoSettings(current);
+  const variants = [
+    { label: `Current: ${PHOTO_MODES[settings.mode].split(' —')[0]} ${settings.threshold}%, contrast ${settings.contrast}`, ...settings },
+    { label: 'Dither, threshold 50, contrast 0', mode: 'dither', threshold: 50, contrast: 0 },
+    { label: 'Dither, threshold 50, contrast 30', mode: 'dither', threshold: 50, contrast: 30 },
+    { label: 'Dither, threshold 60, contrast 30', mode: 'dither', threshold: 60, contrast: 30 },
+    { label: 'Hard threshold 50', mode: 'threshold', threshold: 50, contrast: 0 },
+  ];
+
+  const canvas = createCanvas(
+    gap + variants.length * (tile + gap),
+    gap + tile + caption
+  );
+  const ctx = canvas.getContext('2d');
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+  const abs = photoAbsolutePath(photoPath);
+  let image = null;
+  if (abs) {
+    try {
+      image = await loadImage(abs);
+    } catch {
+      image = null;
+    }
+  }
+
+  for (const [index, variant] of variants.entries()) {
+    const x = gap + index * (tile + gap);
+    if (image) {
+      ctx.drawImage(image, x, gap, tile, tile);
+      halftone(ctx, x, gap, tile, variant);
+    } else {
+      ctx.fillStyle = '#f0f0f0';
+      ctx.fillRect(x, gap, tile, tile);
+      ctx.fillStyle = '#555555';
+      ctx.font = '14px sans-serif';
+      ctx.textAlign = 'center';
+      ctx.fillText('no photo yet', x + tile / 2, gap + tile / 2);
+    }
+    ctx.strokeStyle = '#999999';
+    ctx.lineWidth = 1;
+    ctx.strokeRect(x + 0.5, gap + 0.5, tile, tile);
+
+    ctx.fillStyle = index === 0 ? '#0b4f4a' : '#222222';
+    ctx.font = `${index === 0 ? 'bold ' : ''}13px sans-serif`;
+    ctx.textAlign = 'center';
+    for (const [line, text] of variant.label.split(', contrast').entries()) {
+      ctx.fillText(
+        line === 0 ? text : `contrast${text}`,
+        x + tile / 2,
+        gap + tile + 20 + line * 16
+      );
+    }
+  }
+
+  return canvas.toBuffer('image/png');
 }
 
 /* ------------------------------------------------------------ rendering */
@@ -105,7 +271,10 @@ async function drawBadge(ctx, widthDots, heightDots, visit, site, accent, startY
   if (photo) {
     if (portrait) {
       const x = Math.round((widthDots - photoSize) / 2);
-      if (paint) ctx.drawImage(photo, x, cursorY, photoSize, photoSize);
+      if (paint) {
+        ctx.drawImage(photo, x, cursorY, photoSize, photoSize);
+        halftone(ctx, x, cursorY, photoSize, photoSettings(site));
+      }
       if (paint) {
         ctx.strokeStyle = black;
         ctx.lineWidth = Math.max(2, Math.round(mm(0.3)));
@@ -116,6 +285,7 @@ async function drawBadge(ctx, widthDots, heightDots, visit, site, accent, startY
       const y = Math.round((heightDots - photoSize) / 2);
       if (paint) {
         ctx.drawImage(photo, pad, y, photoSize, photoSize);
+        halftone(ctx, pad, y, photoSize, photoSettings(site));
         ctx.strokeStyle = black;
         ctx.lineWidth = Math.max(2, Math.round(mm(0.3)));
         ctx.strokeRect(pad, y, photoSize, photoSize);
@@ -223,7 +393,8 @@ export async function renderBadgePng(visit, site) {
 
   const design = createCanvas(designW, designH);
   const ctx = design.getContext('2d');
-  const accent = Boolean(site.badge_accent);
+  // Only paint red when the loaded roll can actually print it.
+  const accent = accentWillPrintRed(site);
 
   // Measure first, then draw the block centred down the label. Without this the
   // content hugs the top and leaves a wide blank strip at the bottom of every badge.
@@ -273,6 +444,12 @@ function explainPrintError(output, host) {
   if (/Unknown label|label/i.test(last) && /identifier/i.test(last)) {
     return 'The printer rejected the label size. Check the roll loaded matches the badge settings.';
   }
+  if (/Black\/Red|Monochrome media/i.test(output)) {
+    return 'The printer has a black/red roll loaded but received a monochrome job. Set "Roll loaded in the printer" to the DK-22251 option so the job is built for two-colour tape.';
+  }
+  if (/wrong roll|WrongMedia|media/i.test(last)) {
+    return 'The printer says the roll is wrong. Check "Roll loaded in the printer" matches what is actually in the machine — a black and red job is refused on a plain roll.';
+  }
   return last || 'The printer did not accept the job.';
 }
 
@@ -315,24 +492,33 @@ export async function printBadge(visit, site) {
   const port = Number(site.printer_port) || 9100;
   const target = `tcp://${site.printer_host}:${port}`;
 
-  try {
+  const label = labelFor(site);
-    await runBrotherQl(
+  const args = [
-      [
     '--backend', 'network',
     '--model', site.printer_model || 'QL-820NWB',
     '--printer', target,
     'print',
-        '--label', labelFor(site),
+    '--label', label,
-        file,
+  ];
-      ],
+
-      config.printing.timeoutMs
+  // brother_ql: "You must use this option when printing on black/red tape, even
-    );
+  // when not printing red." Without it the job is built as monochrome, the
+  // printer sees two-colour media, and refuses the whole thing.
+  if (label === '62red') args.push('--red');
+
+  args.push(file);
+
+  try {
+    await runBrotherQl(args, config.printing.timeoutMs);
     note(site.id, true, `Printed to ${site.printer_host}`);
     return { ok: true, target };
   } catch (err) {
     const friendly = explainPrintError(err.message, site.printer_host);
     note(site.id, false, friendly);
-    throw new Error(friendly);
+    const wrapped = new Error(friendly);
+    wrapped.raw = err.message;
+    wrapped.command = `${config.printing.command} ${args.join(' ')}`;
+    throw wrapped;
   } finally {
     fs.rm(file, { force: true }, () => {});
   }

src/routes/admin.js

@@ -392,12 +392,14 @@ router.patch('/sites/:id', (req, res) => {
   const badge = req.body?.badge || {};
   const branding = req.body?.branding || {};
   const printerCfg = req.body?.printer || {};
+  const photoCfg = req.body?.photo || {};
   db.prepare(
     `UPDATE sites SET name = ?, slug = ?, active = ?, badge_enabled = ?, badge_width_mm = ?,
       badge_height_mm = ?, badge_show_photo = ?, badge_accent = ?, badge_note = ?,
       colour_brand = ?, colour_signout = ?, colour_page = ?, colour_text = ?,
       banner_height = ?, banner_align = ?, printer_enabled = ?, printer_host = ?,
-      printer_port = ?, printer_model = ?, printer_rotate = ? WHERE id = ?`
+      printer_port = ?, printer_model = ?, printer_rotate = ?, printer_label = ?,
+      photo_mode = ?, photo_threshold = ?, photo_contrast = ? WHERE id = ?`
   ).run(
     clean(req.body?.name ?? site.name, 100) || site.name,
     req.body?.slug ? uniqueSlug(req.body.slug, site.id) : site.slug,
@@ -432,7 +434,19 @@ router.patch('/sites/:id', (req, res) => {
     printerCfg.model !== undefined ? clean(printerCfg.model, 40) || 'QL-820NWB' : site.printer_model,
     printerCfg.rotate !== undefined
       ? ([0, 90, 180, 270].includes(Number(printerCfg.rotate)) ? Number(printerCfg.rotate) : 0)
-      : site.printer_rotate
+      : site.printer_rotate,
+    printerCfg.label !== undefined
+      ? (Object.hasOwn(printer.ROLL_TYPES, printerCfg.label) ? printerCfg.label : '62')
+      : site.printer_label,
+    photoCfg.mode !== undefined
+      ? (Object.hasOwn(printer.PHOTO_MODES, photoCfg.mode) ? photoCfg.mode : 'dither')
+      : site.photo_mode,
+    photoCfg.threshold !== undefined
+      ? Math.min(95, Math.max(5, Number(photoCfg.threshold) || 50))
+      : site.photo_threshold,
+    photoCfg.contrast !== undefined
+      ? Math.min(100, Math.max(-100, Number(photoCfg.contrast) || 0))
+      : site.photo_contrast
   , site.id);
 
   res.json(shapeSite(db.prepare('SELECT * FROM sites WHERE id = ?').get(site.id)));
@@ -507,10 +521,40 @@ router.post('/sites/:id/test-print', async (req, res) => {
     const result = await printer.printBadge(printer.sampleVisit(site), site);
     res.json({ ok: true, ...result });
   } catch (err) {
-    res.status(400).json({ error: err.message });
+    // The raw output and the exact command matter when the friendly message is
+    // not enough — a printer refusing a job says why in its own words.
+    res.status(400).json({ error: err.message, raw: err.raw || null, command: err.command || null });
   }
 });
 
+/** Everything about how this site would print, for working out why it will not. */
+router.get('/sites/:id/printer-diagnostics', (req, res) => {
+  const site = db.prepare('SELECT * FROM sites WHERE id = ?').get(req.params.id);
+  if (!site) return res.status(404).json({ error: 'Not found.' });
+  res.json({
+    site: site.name,
+    printing: {
+      enabled: Boolean(site.printer_enabled),
+      host: site.printer_host,
+      port: site.printer_port,
+      model: site.printer_model,
+      rotate: site.printer_rotate,
+    },
+    rollSetting: site.printer_label,
+    labelSentToPrinter: printer.labelFor(site),
+    redRequested: Boolean(site.badge_accent),
+    redWillPrint: printer.accentWillPrintRed(site),
+    badgeMm: { width: site.badge_width_mm, height: site.badge_height_mm },
+    lastResult: printer.printerStatus(site.id),
+    command: [
+      'brother_ql --backend network',
+      `--model ${site.printer_model || 'QL-820NWB'}`,
+      `--printer tcp://${site.printer_host}:${site.printer_port || 9100}`,
+      `print --label ${printer.labelFor(site)}${printer.labelFor(site) === '62red' ? ' --red' : ''} badge.png`,
+    ].join(' '),
+  });
+});
+
 /** Reprints a real visitor's badge on the server's printer. */
 router.post('/visits/:id/print', async (req, res) => {
   const visit = db.prepare('SELECT * FROM visits WHERE id = ?').get(req.params.id);
@@ -528,6 +572,37 @@ router.post('/visits/:id/print', async (req, res) => {
   }
 });
 
+/** The same photo at several halftone settings, to choose between by eye. */
+router.get('/sites/:id/photo-preview', async (req, res) => {
+  const site = db.prepare('SELECT * FROM sites WHERE id = ?').get(req.params.id);
+  if (!site) return res.status(404).send('Not found.');
+
+  // Whatever real photo is closest to hand: the most recent visit at this site,
+  // then any stored recurring visitor photo.
+  const recent =
+    db
+      .prepare(
+        'SELECT photo_path FROM visits WHERE site_id = ? AND photo_path IS NOT NULL ORDER BY id DESC LIMIT 1'
+      )
+      .get(site.id) ||
+    db.prepare('SELECT photo_path FROM frequent_visitors WHERE photo_path IS NOT NULL LIMIT 1').get();
+
+  const overrides = {
+    photo_mode: req.query.mode || site.photo_mode,
+    photo_threshold: req.query.threshold || site.photo_threshold,
+    photo_contrast: req.query.contrast || site.photo_contrast,
+  };
+
+  try {
+    const png = await printer.photoPreviewPng(recent?.photo_path || null, overrides);
+    res.setHeader('Content-Type', 'image/png');
+    res.setHeader('Cache-Control', 'no-store');
+    res.send(png);
+  } catch (err) {
+    res.status(500).send(`Could not render the preview: ${err.message}`);
+  }
+});
+
 router.get('/sites/:id/badge-preview', (req, res) => {
   const site = db.prepare('SELECT * FROM sites WHERE id = ?').get(req.params.id);
   if (!site) return res.status(404).send('Not found.');
@@ -1224,6 +1299,38 @@ router.get('/tls/ca.crt', (req, res) => {
   res.send(ca);
 });
 
+/**
+ * The same authority in DER form, for Jamf Pro and anything else built on Apple's
+ * tooling. Offered as .cer and .der because different consoles insist on
+ * different extensions for the identical bytes.
+ */
+router.get(['/tls/ca.cer', '/tls/ca.der'], (req, res) => {
+  try {
+    const der = tls.caCertificateDer();
+    if (!der) return res.status(404).send('No certificate authority has been generated yet.');
+    const ext = req.path.endsWith('.der') ? 'der' : 'cer';
+    res.setHeader('Content-Type', 'application/pkix-cert');
+    res.setHeader('Content-Disposition', `attachment; filename="visitor-signin-ca.${ext}"`);
+    res.send(der);
+  } catch (err) {
+    res.status(500).send(`Could not convert the certificate: ${err.message}`);
+  }
+});
+
+/** All encodings plus instructions, as one archive browsers will actually download. */
+router.get('/tls/ca-bundle.zip', (req, res) => {
+  try {
+    const zip = tls.caBundleZip();
+    if (!zip) return res.status(404).send('No certificate authority has been generated yet.');
+    res.setHeader('Content-Type', 'application/zip');
+    res.setHeader('Content-Disposition', 'attachment; filename="visitor-signin-certificates.zip"');
+    res.setHeader('Content-Length', zip.length);
+    res.send(zip);
+  } catch (err) {
+    res.status(500).send(`Could not build the bundle: ${err.message}`);
+  }
+});
+
 router.post('/tls/renew', requireOwner, (req, res) => {
   try {
     // A brand new CA means every kiosk device has to trust it again, so it is

src/server.js

@@ -72,7 +72,19 @@ app.get('/admin/login', (req, res) => {
 // Nobody should land on the raw filenames; keep one address per page.
 app.get(['/admin.html', '/login.html'], (req, res) => res.redirect('/admin'));
 
-app.use(express.static(publicDir, { extensions: ['html'], index: false }));
+// no-cache still allows a 304 on an unchanged file, but forces the browser to ask
+// first. Without it a cached admin.js survives an upgrade and the console keeps
+// running yesterday's code against today's server, which is impossible to diagnose
+// from the outside.
+app.use(
+  express.static(publicDir, {
+    extensions: ['html'],
+    index: false,
+    setHeaders: (res, filePath) => {
+      if (/\.(html|js|css)$/.test(filePath)) res.setHeader('Cache-Control', 'no-cache');
+    },
+  })
+);
 app.get('/favicon.ico', (req, res) => res.redirect(301, '/favicon.svg'));
 app.use((req, res) => res.status(404).sendFile(path.join(publicDir, 'index.html')));
 
@@ -121,6 +133,45 @@ function startRedirectServer() {
 
   http
     .createServer((req, res) => {
+      // A zip, because browsers block bare certificate downloads.
+      if (req.url === '/ca.zip') {
+        try {
+          const zip = tls.caBundleZip();
+          if (!zip) {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            return res.end('No certificate authority has been generated yet.');
+          }
+          res.writeHead(200, {
+            'Content-Type': 'application/zip',
+            'Content-Disposition': 'attachment; filename="visitor-signin-certificates.zip"',
+            'Content-Length': zip.length,
+          });
+          return res.end(zip);
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          return res.end(`Could not build the bundle: ${err.message}`);
+        }
+      }
+
+      // DER for Apple tooling, PEM for everything else.
+      if (req.url === '/ca.cer' || req.url === '/ca.der') {
+        try {
+          const der = tls.caCertificateDer();
+          if (!der) {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            return res.end('No certificate authority has been generated yet.');
+          }
+          res.writeHead(200, {
+            'Content-Type': 'application/pkix-cert',
+            'Content-Disposition': 'attachment; filename="visitor-signin-ca.cer"',
+          });
+          return res.end(der);
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          return res.end(`Could not convert the certificate: ${err.message}`);
+        }
+      }
+
       if (req.url === '/ca.crt' || req.url === '/ca.pem') {
         const ca = tls.caCertificate();
         if (!ca) {

src/sites.js

@@ -65,6 +65,12 @@ export function shapeSite(site) {
       port: site.printer_port || 9100,
       model: site.printer_model || 'QL-820NWB',
       rotate: site.printer_rotate || 0,
+      label: site.printer_label || '62',
+    },
+    photo: {
+      mode: site.photo_mode || 'dither',
+      threshold: site.photo_threshold ?? 50,
+      contrast: site.photo_contrast ?? 20,
     },
     badge: {
       enabled: Boolean(site.badge_enabled),

src/tls.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import config from './config.js';
+import { createZip } from './zip.js';
 
 /**
  * Certificates for an internal-only kiosk.
@@ -194,6 +195,18 @@ export function ensureCertificates({ force = false } = {}) {
     fs.writeFileSync(p.names, JSON.stringify(config.https.hostnames));
   }
 
+  // A very common mistake is editing .env and then using `docker compose restart`,
+  // which reuses the old environment. The symptom is a certificate covering only
+  // the defaults, so say so rather than letting it fail later in a browser.
+  const configured = config.https.hostnames;
+  if (configured.length === 1 && configured[0] === 'visitors.local') {
+    console.warn(
+      '[tls] HTTPS_HOSTNAMES is at its default. If you set it in .env, bring the container\n' +
+        '      back with "docker compose up -d" rather than "docker compose restart" — restart\n' +
+        '      keeps the environment the container started with.'
+    );
+  }
+
   return {
     key: fs.readFileSync(p.key),
     cert: fs.readFileSync(p.cert),
@@ -225,6 +238,93 @@ export function describe() {
   };
 }
 
+/**
+ * The CA in DER form.
+ *
+ * The .crt on disk is PEM: base64 text between BEGIN/END lines. Apple's tooling,
+ * and therefore Jamf Pro's certificate payload, wants the raw binary DER instead
+ * and rejects the file on its extension. Same certificate, different wrapper.
+ */
+export function caCertificateDer() {
+  const p = paths();
+  if (!fs.existsSync(p.caCert)) return null;
+  return openssl(['x509', '-in', p.caCert, '-outform', 'der']);
+}
+
+/**
+ * Every form of the authority certificate in one archive, with instructions.
+ *
+ * Browsers increasingly refuse to download a bare .crt or .cer as a dangerous
+ * file type, which leaves no way to get the certificate onto a device. A zip is
+ * accepted, and carrying all the encodings means whichever tool is being fed —
+ * Jamf, Windows, Android — has the one it wants.
+ */
+export function caBundleZip() {
+  const p = paths();
+  if (!fs.existsSync(p.caCert)) return null;
+
+  const pem = fs.readFileSync(p.caCert);
+  const der = caCertificateDer();
+  const info = describe();
+
+  const readme = [
+    `${config.siteName} — certificate authority`,
+    '='.repeat(60),
+    '',
+    'Install ONE of these on each device. They are the same certificate in',
+    'different encodings; which one you need depends on the tool.',
+    '',
+    '  visitor-signin-ca.cer   binary DER. Jamf Pro, Apple Configurator, iOS, macOS.',
+    '  visitor-signin-ca.crt   PEM text. Windows, Android, Chromebook, Linux.',
+    '  visitor-signin-ca.pem   identical to the .crt, for tools expecting .pem.',
+    '',
+    'Fingerprint (SHA-256)',
+    `  ${info.ca?.fingerprint || 'unknown'}`,
+    '',
+    'Check this matches what the device shows before trusting it.',
+    '',
+    'Valid until',
+    `  ${info.ca?.validTo || 'unknown'}`,
+    '',
+    'The server certificate currently covers',
+    `  ${(info.server?.names || ['unknown']).join('\n  ')}`,
+    '',
+    'Installing',
+    '----------',
+    'Jamf Pro    Devices > Configuration Profiles > New > Certificate payload.',
+    '            Upload the .cer, scope to the kiosk devices, save. A root',
+    '            certificate delivered by MDM is trusted for TLS automatically.',
+    '',
+    'Windows     Double-click the .crt > Install Certificate > Local Machine >',
+    '            Place all certificates in the following store > Trusted Root',
+    '            Certification Authorities.',
+    '',
+    'Android     Settings > Security > Encryption & credentials > Install a',
+    '            certificate > CA certificate, then pick the .crt. Chrome on',
+    '            Android will not accept a certificate for a bare IP address,',
+    '            so reach the kiosk by hostname.',
+    '',
+    'Chromebook  Settings > Privacy and security > Security > Manage',
+    '            certificates > Authorities > Import, then pick the .crt.',
+    '',
+    'iOS by hand Open the .crt in Safari, allow the profile, install it under',
+    '            Settings > General > VPN & Device Management, THEN turn it on',
+    '            under Settings > General > About > Certificate Trust Settings.',
+    '            Both steps are needed when installing by hand.',
+    '',
+    'Renewing the server certificate does not change this authority, so devices',
+    'only need this done once.',
+    '',
+  ].join('\n');
+
+  return createZip([
+    { name: 'visitor-signin-ca.cer', data: der },
+    { name: 'visitor-signin-ca.crt', data: pem },
+    { name: 'visitor-signin-ca.pem', data: pem },
+    { name: 'README.txt', data: readme },
+  ]);
+}
+
 export function caCertificate() {
   const p = paths();
   return fs.existsSync(p.caCert) ? fs.readFileSync(p.caCert) : null;

src/zip.js

@@ -0,0 +1,108 @@
+import zlib from 'node:zlib';
+
+/**
+ * A small ZIP writer, so a bundle of certificates can be offered as a single
+ * download. Browsers increasingly refuse .crt and .cer files as dangerous types,
+ * and a zip is accepted where the bare certificate is not.
+ *
+ * Only what is needed here: a handful of small files, no directories, no
+ * encryption, no zip64. Written directly rather than pulling in a dependency for
+ * sixty lines of header packing.
+ */
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let crc = -1;
+  for (const byte of buffer) crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ byte) & 0xff];
+  return (crc ^ -1) >>> 0;
+}
+
+/** MS-DOS packs the date and time into two 16 bit words, with two second resolution. */
+function dosStamp(date) {
+  const time =
+    (date.getHours() << 11) | (date.getMinutes() << 5) | Math.floor(date.getSeconds() / 2);
+  const day = ((date.getFullYear() - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
+  return { time, day };
+}
+
+/**
+ * @param {Array<{name: string, data: Buffer|string}>} files
+ * @returns {Buffer} the complete archive
+ */
+export function createZip(files) {
+  const now = new Date();
+  const { time, day } = dosStamp(now);
+  const locals = [];
+  const central = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const name = Buffer.from(file.name, 'utf8');
+    const raw = Buffer.isBuffer(file.data) ? file.data : Buffer.from(file.data, 'utf8');
+    const compressed = zlib.deflateRawSync(raw);
+    // Storing uncompressed is allowed and is smaller for data that does not shrink.
+    const useDeflate = compressed.length < raw.length;
+    const data = useDeflate ? compressed : raw;
+    const method = useDeflate ? 8 : 0;
+    const crc = crc32(raw);
+
+    const localHeader = Buffer.alloc(30);
+    localHeader.writeUInt32LE(0x04034b50, 0); // local file header signature
+    localHeader.writeUInt16LE(20, 4); // version needed
+    localHeader.writeUInt16LE(0, 6); // flags
+    localHeader.writeUInt16LE(method, 8);
+    localHeader.writeUInt16LE(time, 10);
+    localHeader.writeUInt16LE(day, 12);
+    localHeader.writeUInt32LE(crc, 14);
+    localHeader.writeUInt32LE(data.length, 18);
+    localHeader.writeUInt32LE(raw.length, 22);
+    localHeader.writeUInt16LE(name.length, 26);
+    localHeader.writeUInt16LE(0, 28); // extra field length
+
+    locals.push(localHeader, name, data);
+
+    const centralHeader = Buffer.alloc(46);
+    centralHeader.writeUInt32LE(0x02014b50, 0); // central directory signature
+    centralHeader.writeUInt16LE(20, 4); // version made by
+    centralHeader.writeUInt16LE(20, 6); // version needed
+    centralHeader.writeUInt16LE(0, 8);
+    centralHeader.writeUInt16LE(method, 10);
+    centralHeader.writeUInt16LE(time, 12);
+    centralHeader.writeUInt16LE(day, 14);
+    centralHeader.writeUInt32LE(crc, 16);
+    centralHeader.writeUInt32LE(data.length, 20);
+    centralHeader.writeUInt32LE(raw.length, 24);
+    centralHeader.writeUInt16LE(name.length, 28);
+    centralHeader.writeUInt16LE(0, 30); // extra
+    centralHeader.writeUInt16LE(0, 32); // comment
+    centralHeader.writeUInt16LE(0, 34); // disk number
+    centralHeader.writeUInt16LE(0, 36); // internal attributes
+    centralHeader.writeUInt32LE(0, 38); // external attributes
+    centralHeader.writeUInt32LE(offset, 42); // offset of local header
+
+    central.push(centralHeader, name);
+    offset += localHeader.length + name.length + data.length;
+  }
+
+  const centralBuffer = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0); // end of central directory
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(centralBuffer.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20); // comment length
+
+  return Buffer.concat([...locals, centralBuffer, end]);
+}

tatus

@@ -0,0 +1,3 @@
+b1a7933 (HEAD -> deploy) Printer Debug 2
+eb98658 Printing Debug
+8bc7179 (origin/deploy) Server-side printing, roll type setting, cache headers