Files
simple-aircraft-manager-rails/docs/guide/administration.md
T
rickyandClaude Opus 5.5 b4c7aaa3ff Invitation codes: a link that gives an account and roles
Ported from the original (InvitationCode), adapted to configurable roles.

- Admin → Invitations: a label, optionally one email address (only it can
  use the link, and it's emailed) and a name, how many uses (or
  unlimited), an expiry (or never), and a role on any aircraft (or none,
  for an account only).
- An aircraft's Access page: whoever manages its people invites to that
  aircraft, with only the roles they can give; they see and revoke its
  invitations.
- /join/<code>: shows what it gives; create an account (when password
  sign-in is on) or sign in, then accept. Existing accounts and SSO users
  accept too. A role someone already has on an aircraft stays.
- Roles are given as the invitation's creator (AircraftAccess), and only
  while they can still manage that aircraft's people. Codes are kept as
  digests and shown once; uses are counted under a lock; account creation
  and accepting are rate-limited; any invalid link gets the same answer.
- Docs: guide (Administration, Access & sharing), README, and why /join
  isn't on the Authentik bypass list. The README's not-yet-ported list
  now names Prometheus metrics, and no longer claims oil analysis import
  as new.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 18:50:58 -05:00

15 KiB

Administration

Admins see the Admin menu (on a phone, under ☰). Admins can see and edit every aircraft.

Users

Users lists every account.

  • + New User: name, email and a starting password. Tick Administrator to make them an admin. Then give them a role on aircraft: Edit → Aircraft access lists their role on every aircraft, to add, change or remove (an aircraft's Owner can also do it from More → Access & sharing, and anyone can add their own aircraft).
  • Edit to change details or reset a password when email isn't set up.
  • Locked marks an account locked for 15 minutes after 10 failed sign-ins in a row (the user is emailed). Unlock clears it straight away, once you know it was really them.
  • 2FA marks someone using an authenticator app. Reset 2FA turns it off for a user who lost their phone and recovery codes. Confirm it's really them first (call them); they can then set it up again.
  • Disable someone who no longer needs access: they're signed out and can't sign in or sign entries, and their past signatures stay. Enable reverses it. Users who have signed entries can't be deleted, only disabled.

With single sign-on, accounts can be created automatically at first sign-in, and admin rights can follow a group at the provider (see the main README).

Roles

Admin → Roles sets what people can do on an aircraft. Each person has one role per aircraft; a role is a set of permissions, grouped as flying, squawks and notes, maintenance records, imports and exports, the aircraft itself, and notifications. Everyone can see the records of the aircraft they have a role on; the permissions are for changing things.

  • Owner always has every permission, so every aircraft can always be managed. Its name and description can be changed.
  • Mechanic, Pilot and Viewer come with sensible permissions (the table in Getting started) that you can change.
  • New role adds your own, such as a partner, an instructor or an insurer. A role can be deleted once nobody has it.

Signing a logbook entry needs the Sign logbook entries permission and a current certificate on the person's profile. Get reminders decides who receives the weekly email of what's coming due and the alerts when something becomes overdue.

To give someone a role on any aircraft, open them in Admin → Users: Aircraft access lists their role on each aircraft, to change, remove or add.

Invitations

Admin → Invitations → New invitation makes a link someone opens to create their own account (or accept with the one they have) and get roles on aircraft: a label for you, optionally an email address (then only that address can use it, and the link is emailed to it when email is set up) and a name, how many times it works (empty for unlimited, e.g. for a flying club), when it expires (empty for never), and a role on any of the aircraft (none at all gives just an account). The link is shown once, when it's made; copy it then.

Where someone already has a role on an aircraft, an invitation leaves it as it is. An invitation never gives more than whoever made it can give when it's used. Revoke stops a link working; people who already used it keep their access. With sign-in by single sign-on only, people accept invitations after signing in with it.

Account recovery from the command line

If nobody can sign in to fix an account in the app (a forgotten admin password, a lockout, a lost phone with no recovery codes, the only admin disabled), run these on the server. With Docker Compose, put docker compose exec web in front; in Portainer, open the container's Console and run them there. Anyone who can run commands on the server already has the data, so they ask for nothing else. Each one is written to the log.

Command What it does
bin/rails users:list Lists accounts, with admin, disabled, locked, 2FA and SSO status
bin/rails "users:reset_password[jane@example.com]" Sets a new generated password and shows it once; also unlocks the account and signs it out everywhere. PASSWORD=... in front sets your own instead (it then stays in your shell history)
bin/rails "users:sign_in_link[jane@example.com]" Prints a one-time sign-in link (15 minutes), for when email isn't working. Two-factor still asks for the code
bin/rails "users:unlock[jane@example.com]" Clears a lockout after failed sign-ins
bin/rails "users:reset_two_factor[jane@example.com]" Turns off the authenticator app
bin/rails "users:enable[jane@example.com]" / users:disable[…] Enables or disables an account
bin/rails "users:make_admin[jane@example.com]" Makes an existing account an admin (with OIDC_ADMIN_GROUP set, the next single sign-on sets it from the group again)
bin/rails "users:create_admin[jane@example.com,Jane Pilot]" Creates a new admin account with a generated password

Keep the quotes around commands with brackets: some shells treat [ specially.

If single sign-on is broken and PASSWORD_LOGIN=false is set, remove that setting and restart first, so password sign-in (and sign-in links) work again.

Component Types, Airports, Logbook Templates

  • Component Types: the list of types used for components (owners can also add new types while adding a component).
  • Airports: airport data from OurAirports, used for From/To autocomplete and AirTrail. It downloads by itself when the app first starts; Update from OurAirports refreshes it. Add private strips here; they're never overwritten.
  • Logbook Templates: the wording offered when writing an entry. Use __ for blanks. Restore built-in templates adds back any deleted built-in ones.

Settings

  • Uploads: the largest file anyone can upload. A proxy in front of the app may have its own smaller limit.
  • Backups: how many nightly database copies to keep, on the server and in Google Drive.
  • Document search: read scanned documents with Tesseract (free, on the server) or Claude (better on handwriting, needs ANTHROPIC_API_KEY, costs API credit). PDFs with text are read directly either way.

About

About shows the running version (year.month.release, e.g. 2026.11.0) and build (the exact source commit), What's new in this version, with a link to all releases (also under Help → What's new, where older releases are folded to one line each), and the features and storage. It has tools:

  • Send test email and Send me this week's reminder check that email works.
  • Records integrity: the last nightly backup, off-site copy and records check. Back up and check now runs the backup and check straight away.
  • Records: the current recordkeeping procedures revision, the last audit and when the next is due.
  • Software versions: when each version of the app was first run.

Backups

Every night at 3:30 the app makes a verified copy of the database in storage/backups, then checks the record history and every signature. Admins are emailed if anything fails.

Those copies sit on the same server, so the records also need a copy somewhere else. The app can make that copy to Google Drive itself (below). Otherwise back up the whole storage volume to another machine or a cloud service, and test restoring it now and then. A restore test is part of every records audit.

Off-site backup to Google Drive

Admin → Off-site Backup connects a Google account. Every night after the database backup, the app copies to that account's Drive:

  • the verified database copy, compressed (database/sam-….sqlite3.gz), keeping the newest 30 (change it in Settings);
  • every uploaded file (scans, documents, photos, track logs) not already copied (files/). Files are never deleted there, so one deleted here by mistake can still be recovered.

The app can only see the files it created in your Drive. Admins are emailed if a copy fails, and the About page shows the last one.

Google Drive is the only cloud service built in. iCloud Drive can't be used: Apple offers no way for a server to upload to it. To use iCloud anyway, a Mac signed in to iCloud can copy storage/backups and the uploaded files into iCloud Drive on a schedule; describe that in the procedures' off-site backup field, since the app can't check it.

Setting it up (once)

You create your own Google "OAuth client" so the app can ask for access. The steps are also on the page:

  1. In the Google Cloud console, signed in as the account that will hold the backups, create a project and enable the Google Drive API.
  2. Under Google Auth Platform, fill in Branding (an app name and your email). Under Audience, choose External, then Publish app. While it's left in "Testing", Google ends the access after 7 days. Google doesn't need to verify it, because the app only asks for access to files it creates.
  3. Under Clients, create an OAuth client ID of type Web application, with the redirect URI shown on the Off-site Backup page (it ends in /admin/offsite_backup/callback, at the address you use for the app).
  4. Paste the client ID and secret on the page, choose Save client, then Connect Google Drive and allow access. Google warns that the app isn't verified: choose Advanced → Go to ….

The first backup starts straight away. It copies every uploaded file, so it can take a while.

Back up now runs a backup straight away. Test restore downloads the newest database copy from Drive, opens it and checks it, and downloads a few random files and compares them with their checksums. Disconnect stops the copies; what's already in Drive stays there.

Restoring from Google Drive

If the server is lost:

  1. Set up the app again (see the main README) with the same SECRET_KEY_BASE, but don't start it yet.
  2. From Google Drive, download the newest file in Simple Aircraft Manager backups → database (sam-….sqlite3.gz) and copy it onto the server.
  3. Put it in place: bin/rails "backups:restore[/path/to/sam-….sqlite3.gz]". With Docker, run it in a one-off container while the app is stopped: docker compose run --rm web bin/rails "backups:restore[/rails/storage/sam-….sqlite3.gz]" (copy the file into the storage volume first). It checks the copy, keeps any existing database aside, and asks before replacing.
  4. Start the app and sign in. The records are back, but uploaded files are still missing.
  5. Restore the files: bin/rails offsite:restore_files downloads them from Drive (the connection is in the restored database). If that doesn't work (for example the SECRET_KEY_BASE is lost), download the files folder from Drive, unzip it on the server and run bin/rails "offsite:restore_files[/path/to/files]".
  6. Check everything: bin/rails records:check (history and signatures intact) and bin/rails sam:doctor, then open a few entries and documents.

The same backups:restore (with no file) puts back the newest nightly copy from storage/backups, for example after a mistake that can't be undone in the app; bin/rails backups:list shows the copies.

Maintenance commands

Run on the server like the account recovery commands (docker compose exec web in front, or the container's Console in Portainer).

Command What it does
bin/rails sam:doctor Health report: secret key (set and long enough), address, HTTPS, email (SMTP reachable), single sign-on (issuer reachable), Google Drive, migrations, disk space, background jobs, and how recent the backup, records check, off-site copy, procedures and audit are. Exits non-zero if something fails
bin/rails records:check Backs up the database now and checks the record history and every signature; prints any problems and exits non-zero
bin/rails backups:list Lists the nightly database copies
bin/rails "backups:restore[file]" Replaces the database with a backup (newest nightly copy if no file; a Google Drive .sqlite3.gz works too). The app must be stopped: docker compose stop web, then docker compose run --rm web bin/rails backups:restore. The current database is moved to storage/pre-restore-…, never deleted. CONFIRM=yes skips the question
bin/rails users:sign_out_all Signs every user out of every device, if you think an account or session was compromised
bin/rails "sam:records_package[N12345]" Writes the aircraft's records package to a zip, for when the web side is down
bin/rails "email:test[you@example.com]" Sends a test email and shows the mail settings
bin/rails offsite:backup / offsite:restore_test Runs the Google Drive copy or a restore test now and prints the result

Recordkeeping procedures

If the app replaces the paper logbooks, AC 120-78B asks for a written procedures document. Recordkeeping Procedures generates one from the app's setup:

  1. Fill in the details the app can't know: the owner/operator, the person responsible for the records, how the app is hosted, how it's backed up off-site (described automatically when Google Drive is connected), and how often to audit and how many entries to sample. Insert suggested text under Hosting and network and Additional procedures fills the box with a starting draft: what the app knows from its settings (HTTPS, how people sign in, the password and lockout rules, the date electronic records began) and common procedures for a Part 91 owner (who signs, outside signers, share links, retention, paper records, sale). Replace each [bracketed] blank with your own details and change anything that isn't how you work; a revision can't be adopted while a blank is left.
  2. Preview the draft and read it through.
  3. Adopt it as a revision, with a note of what changed. Adopted revisions can't be changed; print one or save it as a PDF with the records.

The document covers responsible personnel, users and roles, the signing process, system controls, audits, making records available to the FAA, transfer, continuity and changes, with these user instructions as an appendix. Adopt a new revision whenever users, hosting or procedures change. The current revision goes into each aircraft's records package.

Records audits

Records Audits is the periodic quality check the procedures promise. Start an audit:

  • The app shows its own checks: the latest integrity check, backup and off-site copy, the procedures, signatures, expired certificates, and software changes since the last audit.
  • You confirm the rest: that you restored the off-site backup somewhere separate and opened it (with Google Drive, run Test restore and also open a downloaded copy yourself); that a random sample of entries matches their work orders or receipts; that the users and roles are right (disable anyone who no longer needs access); and that the paper logbooks are kept.
  • Add a note for each item and overall, then Record audit. Audits can't be changed afterwards.

The next one is due after the interval set in the procedures. It shows on About, and admins are reminded in the weekly email.