Admin guide

For the fleet program administrator: setting up devices and access codes, loading the fleet, changing checklists and rules, backups, resets and troubleshooting. Members should read the user guide.

1. How the system fits together

• The app runs in the browser. Each device keeps its own full copy of the records, so it works offline.
• The server (api.php) only does two things: it accepts new records and hands out records a device hasn't seen yet. It needs a valid access code for both.
• The data is plain text: one file per record type (records/units.jsonl, inspections.jsonl, lockouts.jsonl…), one record per line. It lives in ~/fvm-data, outside the public website folder, so it can't be downloaded from the web.
• Records are append-only. Nothing is edited or deleted. Each change is a new record with a unique ID and a SHA-256 fingerprint, and current status (in service, locked out, PM due…) is worked out by replaying the records in order. This gives a complete audit trail.
• Rules are data too. Checklists, inventories, PM intervals and program rules are JSON files in config/.

Full technical detail: DATA-MODEL.md.

2. First-time setup checklist

1. Issue the department's access code(s) — section 3. Retire the test code once real data goes in.
2. Review config/program.json against your SOPs: lock-out steps, release roles, check-out purposes, the 12-hour pre-trip window — section 7.
3. Clear any test or demo data from the server and devices — section 9.
4. Import the fleet roster from the spreadsheet — section 5.
5. Place lock-outs for any units already out of service, and record the last known PM / service test dates so due dates start correctly.
6. Hand out the device setup card and the access code.
7. Set a backup routine — section 8.

3. Access codes

Give every person their own code (or one per shared station tablet). Everything a code uploads is stamped with its name, and the server logs each upload with the internet address it came from, so changes can be traced. A code can be cut off at once without re-keying anyone else.

Roles

In the app (recommended)

1. Connect your own device with an administrator code. Data & settings › Server then shows Manage access codes.
2. Issue: enter the person's name, badge ID and role › Issue code. The code is shown once — copy it or press Print slip and hand it over in person. The server keeps only a fingerprint; a lost code can't be looked up, only replaced.
3. Deactivate: press Deactivate on the person's row — for a member leaving, a lost phone, or a code that may have spread. Their devices show Access code rejected on the next sync; records already uploaded stay. Reactivate undoes it.
4. Change role with the drop-down on the row.
5. Recent activity lists every upload (with unit names for fleet changes), code change and refused code, with time and internet address. Use the filter to find, for example, every change to “Engine 9-1”.

You can't deactivate or demote the code you're signed in with, and at least one active administrator code must remain.

From the server shell (backup method)

cPanel › Terminal or SSH, in the program folder:

cd ~/fleet.spcfpd.org
php api.php list-keys                                  # every code: id, name, role, active, last used
php api.php issue-key "Pat Rivera" officer 417         # new code (printed once): name, role, badge ID
php api.php deactivate-key "Pat Rivera"                # cut off (name or id)
php api.php reactivate-key "Pat Rivera"

Use the shell if every administrator code is lost: php api.php issue-key "New admin" admin.

4. Setting up devices

• Give each member the device setup card (one printable page) and the access code.
• Server address is api.php (the default) or https://fleet.spcfpd.org/api.php.
• Settings — name, member ID, role, server address and code — are stored only in that browser. A new phone, a different browser or a private window starts blank.
• Shared station tablets: leave Your name blank so each member types their own name on each form.
• Data & settings also has Test (checks the code without syncing), Disconnect, and Re-download everything (rebuilds the device's copy from the server).

5. Loading and updating the fleet

From the spreadsheet template

1. In the app: Fleet › Import / update from spreadsheet › Download Excel template. It has drop-downs, an Instructions tab and a Unit types tab.
2. One row per vehicle. Only Unit name and Unit type are required. Equipment columns: Y / N only where a unit differs from its type's defaults.
3. Choose the file (.xlsx or .csv). The preview marks each row New, Update, No change or Skipped with the reason. Nothing is saved until you press Import.
4. Import on one device only. The others download the units by syncing. Importing the same new file on two devices creates every unit twice.

Updating later

• Download current fleet (CSV) gives the same columns plus a hidden System ID. Edit and re-import it — units match by System ID, then by name, so renames update in place.
• Blank cells keep the current value; they never erase data.
• Asset No. is always the last 6 characters of the VIN. A different value in the sheet is replaced, with a warning. Type one only for units with no VIN.
• Reading .xlsx needs internet the first time (the Excel reader loads from a public CDN). CSV always works offline.

From the district Apparatus Master

The converter turns the Apparatus Master workbook's Fleet Master tab into an import file. It maps Current Assignment to unit name, Chassis Type to unit type, Date Acquired to in-service date and Mileage to odometer, and carries pump hours, priority and notes into Notes:

cd ~/fleet.spcfpd.org
python3 tools/convert_apparatus_master.py ~/fvm-imports/ApparatusMaster.xlsx ~/fvm-imports/fleet-import.xlsx

6. Unit types, retiring and renaming

• Unit type decides the checklist sections, inventory and PM tasks. Types: structure engine, wildland engine, water tender, ladder / aerial, heavy rescue / squad, ambulance (ALS / BLS), medical response vehicle, medical ride share / NEMT, command, utility, and specialty (boat / UTV / trailer).
• Equipment fine-tunes it per unit — a quint is a ladder with a pump; a wildland engine may carry SCBA. Edit it on the unit's Edit page or with Y/N columns in the import.
• Reserve units aren't flagged for missed daily checks. Retired units drop off the board and unit pickers (shown under All incl. retired), lose their action buttons and can't be checked out; their history stays.
• Units are never deleted. Retire a unit that's sold or disposed of.

7. Checklists, inventory, PM and rules

• Edit with any text editor (cPanel File Manager works), then check the JSON is valid — a missing comma stops the app from loading. Keep a copy of the file before editing.
• Raise the version in the file you changed. Each inspection stores the checklists.json version it was made with, so later audits know which checklist applied.
• Changes reach devices the next time each one opens the app online. Old records are not changed.
• Keep item ids stable — reports and work-order matching use them. Add new IDs rather than reusing old ones.
• After changing unit types or equipment in apparatus.json, rebuild the import template: python3 tools/make_fleet_template.py.

8. Backups and recovery

Server copy

Back up the whole ~/fvm-data folder — it's the master copy. Your host's account backups include it; for an extra copy:

tar czf ~/fvm-backup-$(date +%F).tar.gz -C ~ fvm-data

Download that file and keep it off the server. Restoring is copying the folder back.

From the app

• Data & settings › Backup file downloads every record on that device as one file. Add a passphrase to encrypt it (AES-256). Import file(s)… loads a backup on any device; records already present are skipped.
• Thumb drive / folder (Chrome or Edge on laptops / Android) keeps a full copy in the same file layout as the server, merging both ways. Useful as an offline master or for moving data without the internet.
• Spreadsheet exports (CSV) — fleet, inspections, defects found, inventory issues, lock-outs, check-outs, work orders, PM and service tests — for reports and audits.

9. Clearing test data / starting over

Because records are never deleted inside the app, clearing test data is done on the server and on each device:

1. Server — move the record files into an archive folder (keeps server.json, so access codes still work):

   A=~/fvm-data-archive/$(date +%F); mkdir -p "$A"
   flock ~/fvm-data/.lock sh -c "mv ~/fvm-data/records ~/fvm-data/ids.txt ~/fvm-data/seq.txt ~/fvm-data/fleet.json ~/fvm-data/manifest.json $A/ && mkdir -m 750 ~/fvm-data/records"

2. Every device that has used the app — Data & settings › Erase this device › Erase local data. This keeps the name, server address and access code. Do it after the server reset and before the device syncs again, otherwise it keeps showing old units and misses the first new records.
3. Thumb-drive folders — delete the FireVehicleMgmt folder, or it brings old records back.
4. Import the fleet on one device, then open the app on the others.

10. Updating the program

• The app checks the server first every time it opens, so updated files reach devices on their next online visit; the offline copy is the fallback.
• When changing the program's JavaScript or CSS, raise CACHE in sw.js (e.g. fvm-v4) and the ?v= number on js/app.js in index.html, so every device refreshes its offline copy.
• The .htaccess file tells browsers not to cache scripts, styles or config, and blocks api-config.php and Python tools from the web. Keep it.
• Data files are never touched by a program update.

11. Security and accountability

• Access codes are the gate. Anyone with a code can read the fleet records and add records; only officer and administrator codes can change the fleet roster. Issue one code per person and deactivate it the day they leave or lose a phone.
• Names typed on forms aren't verified, the access code is. Each record shows the name entered and, once uploaded, the name of the code that uploaded it (record view › “Uploaded with access code”). The activity log adds the internet address.
• Release authority is by role selection. The app requires a releasing role and records it, but can't check it. Officers should review the Records list for lock-out releases and overrides.
• Integrity. Each record's SHA-256 fingerprint is checked when it's opened. Integrity check failed means the record was altered after signing; investigate.
• The data folder is outside the web root and blocked by .htaccess. The site must stay on HTTPS.
• The records hold no patient information. Keep it that way — use run numbers, not names, in notes.

12. Troubleshooting

13. Moving to a database later

Each records/*.jsonl file maps one-to-one to a database table, and every record has a unique ID, so loading them is a straight insert that is safe to repeat. Replace api.php with an endpoint that speaks the same two calls (push and pull) and the app doesn't change. That stage is the right time to add per-person sign-in and role-checked lock-out release. Details: DATA-MODEL.md §6–7.