Records package viewer: read-only, no account needed

SAM_VIEWER=true (set only by the records package's
viewer/docker-compose.yml) makes the app a read-only copy of an archive,
for whoever receives the records: `docker compose up`, then open
http://localhost:3000.

- At start (bin/docker-entrypoint → sam:viewer:prepare) the package's
  .sam.zip, mounted read-only, is imported once.
- No sign-in: everyone browses as a built-in account. Nothing can be
  changed: any request but GET/HEAD is refused, no role permission
  applies (so no edit buttons), and there's no sign-out or profile. A
  banner names the archive and when it was exported.
- It refuses to start, and every page answers 503, when the database
  has any other account, so turning it on for a real installation stops
  the app instead of exposing its records.
- The viewer listens on 127.0.0.1 only, and skips scheduled jobs
  (reminders, backups, AD searches).
- Docs: the package README (three steps now), Access & sharing, README
  settings and features, the suggested recordkeeping procedures.

Checked end to end with a built image and a real records package: the
archive imported at start, pages browsed without an account, a change
refused, and the container refusing to start once an account existed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-15 20:03:56 -05:00
1 parent 34e3232350
commit d956cfbe83
14 files changed
+229 -33

No files matched your search

+13
View File
@@ -6,6 +6,7 @@ class ApplicationController < ActionController::Base
include RejectsNullBytes
prepend_before_action :redirect_to_setup
prepend_before_action :viewer_guard # first (see Viewer)
before_action { Current.ip_address = request.remote_ip } # for record history
helper_method :current_user
@@ -40,6 +41,18 @@ class ApplicationController < ActionController::Base
def current_user = Current.user
# First run: no users yet → create the initial admin.
# Viewer mode: never with real accounts, and nothing can be changed.
def viewer_guard
return unless Viewer.enabled?
return render(plain: Viewer::RealAccounts.new.message, status: :service_unavailable) if Viewer.real_accounts?
Viewer.user
return if request.get? || request.head?
respond_to do |format|
format.html { redirect_back fallback_location: root_path, alert: t("viewer.read_only") }
format.any { head :forbidden }
end
end
def redirect_to_setup
redirect_to new_setup_path if !User.exists? && !is_a?(SetupController)
end
+3 -2
View File
@@ -49,10 +49,11 @@ module AircraftScoped
@current_role = current_user.role_for(@aircraft)
end
def can?(permission) = current_user.admin? || current_role&.can?(permission) || false
# Nothing in viewer mode (a read-only copy, see Viewer).
def can?(permission) = !Viewer.enabled? && (current_user.admin? || current_role&.can?(permission) || false)
# The Owner role (or an administrator): everything.
def owner? = current_user.admin? || current_role&.owner? || false
def owner? = !Viewer.enabled? && (current_user.admin? || current_role&.owner? || false)
def authorize_permission!
rules = self.class.permission_rules.select do |_, only, except|
+6 -1
View File
@@ -21,7 +21,12 @@ module Authentication
end
def require_authentication
resume_session || request_authentication
resume_session || start_viewer_session || request_authentication
end
# Viewer mode: everyone is its built-in account, without signing in.
def start_viewer_session
start_new_session_for(Viewer.user) if Viewer.enabled? && !Viewer.real_accounts?
end
def resume_session
+2 -1
View File
@@ -123,10 +123,11 @@ class User < ApplicationRecord
# Adding an aircraft (or importing one) makes you its Owner: administrators,
# or everyone when Admin → Settings allows it.
def can_add_aircraft? = admin? || Setting.anyone_adds_aircraft?
def can_add_aircraft? = !Viewer.enabled? && (admin? || Setting.anyone_adds_aircraft?)
# Administrators can do everything on every aircraft.
def can?(permission, aircraft)
return false if Viewer.enabled?
admin? || role_for(aircraft)&.can?(permission) || false
end
+63
View File
@@ -0,0 +1,63 @@
# Viewer mode (SAM_VIEWER=true): a read-only copy of an aircraft archive for
# whoever receives a records package (the FAA, a buyer), with no sign-in. It's
# what the package's viewer/docker-compose.yml runs, on that person's own
# computer.
#
# - At start (bin/rails sam:viewer:prepare, from bin/docker-entrypoint), the
# archive at SAM_VIEWER_ARCHIVE is imported, owned by a built-in account.
# - Everyone is that account (Authentication): no sign-in.
# - Nothing can be changed: requests other than GET/HEAD are refused
# (ApplicationController), and no role permission applies (AircraftScoped).
#
# So that it can never open a real installation, it refuses to run when the
# database has any account other than the built-in one: setting SAM_VIEWER on
# a real server stops it rather than exposing its records.
module Viewer
EMAIL = "viewer@sam-viewer.invalid".freeze
class RealAccounts < StandardError
def message = "SAM_VIEWER is on, but this database has user accounts: viewer mode is only for an empty " \
"copy made to look at an archive. Turn SAM_VIEWER off for a real installation."
end
def self.enabled? = ENV["SAM_VIEWER"] == "true"
def self.archive = ENV["SAM_VIEWER_ARCHIVE"].presence
# What was imported, for the banner (kept with the data).
def self.info_path = Pathname(ENV["SAM_VIEWER_INFO"].presence || Rails.root.join("storage/viewer.json"))
def self.real_accounts? = User.where.not(email_address: EMAIL).exists?
# The built-in account everyone browses as (made when first needed). It
# can't sign in by password: nobody knows it.
def self.user
User.find_or_create_by!(email_address: EMAIL) do |u|
u.name = I18n.t("viewer.account_name")
u.password = SecureRandom.base58(40)
end
end
# Checks the database, then imports the archive the first time.
def self.prepare!(output: $stdout)
raise RealAccounts if real_accounts?
owner = user
if Aircraft.exists?
output.puts "Viewer: already imported (#{Aircraft.ordered.pluck(:tail_number).join(', ')})."
elsif archive.nil? || !File.file?(archive)
output.puts "Viewer: no archive at SAM_VIEWER_ARCHIVE (#{archive.inspect}); nothing to show."
else
output.puts "Viewer: importing #{File.basename(archive)}…"
preview = AircraftArchive::Importer.check(archive)
result = AircraftArchive::Importer.new(archive, owner: owner).run
File.write(info_path, { file: File.basename(archive), tail_number: result[:aircraft].tail_number,
exported_at: preview.exported_at&.iso8601 }.to_json)
output.puts "Viewer: imported #{result[:aircraft].tail_number}: #{result[:counts].map { |k, n| "#{n} #{k.tr('_', ' ')}" }.join(', ')}"
end
output.puts "Viewer ready: open http://localhost:3000"
end
# What the banner says: the archive's file and when it was exported.
def self.info
JSON.parse(info_path.read) if info_path.file?
rescue JSON::ParserError
nil
end
end
+14 -9
View File
@@ -76,30 +76,35 @@ class RecordsPackage
"#{image.sub(/:[^:\/]+\z/, '')}:#{version}"
end
# A ready-to-run local viewer, with its own throwaway secret key (never this
# installation's), plain HTTP on localhost.
# A ready-to-run local viewer of the archive: read-only, no account needed
# (viewer mode, see Viewer), reachable only from that computer, with its own
# throwaway secret key (never this installation's).
def viewer_compose
image = viewer_image
archive = "#{@aircraft.tail_number.downcase}.sam.zip"
<<~YAML
# Simple Aircraft Manager on your own computer, to browse #{@aircraft.tail_number.downcase}.sam.zip.
# 1. docker compose up -d
# 2. Open http://localhost:3000 and create the first (admin) account. It asks
# for a one-time setup code: docker compose logs web | grep "Setup code"
# 3. Fleet -> More -> Import from a .sam.zip archive: choose #{@aircraft.tail_number.downcase}.sam.zip
# Stop: docker compose down (add -v to delete this local copy)
# Simple Aircraft Manager on your own computer, showing #{archive} read-only.
# 1. In this folder: docker compose up
# The first start imports the records; wait for "Viewer ready".
# 2. Open http://localhost:3000 (no account needed).
# Stop: Ctrl+C, then docker compose down (add -v to delete this local copy).
# Prepared with software version #{SystemInfo.new.version_label}.#{" Source: #{repository}" if repository}
services:
web:
#{image ? "image: #{image}" : "build: . # no published image known: build from the source code"}
restart: "no"
ports:
- "3000:80"
- "127.0.0.1:3000:80" # this computer only
environment:
SAM_VIEWER: "true"
SAM_VIEWER_ARCHIVE: /import/#{archive}
SECRET_KEY_BASE: #{SecureRandom.hex(64)} # for this local copy only
APP_HOST: localhost:3000
FORCE_SSL: "false"
SOLID_QUEUE_IN_PUMA: "true"
SOLID_QUEUE_SKIP_RECURRING: "true" # no reminders, backups or AD searches
volumes:
- ../#{archive}:/import/#{archive}:ro # the archive next to this folder, in the package
- viewer_storage:/rails/storage
volumes:
viewer_storage:
+11 -4
View File
@@ -45,7 +45,7 @@
<summary class="flex cursor-pointer list-none items-center rounded px-3 py-2 text-lg leading-none hover:bg-white/10 [&::-webkit-details-marker]:hidden" aria-label="<%= t(".menu") %>">☰</summary>
<div class="absolute right-0 z-30 mt-2 w-56 rounded-md bg-surface py-1 text-slate-700 shadow-lg ring-1 ring-slate-200">
<p class="truncate px-4 pt-2 pb-1 text-xs text-slate-500"><%= current_user.email_address %></p>
<%= link_to t(".profile"), edit_profile_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
<% unless Viewer.enabled? %><%= link_to t(".profile"), edit_profile_path, class: "block px-4 py-2.5 hover:bg-slate-100" %><% end %>
<%= link_to t(".search"), search_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
<%= link_to t(".help"), help_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
<% if current_user.admin? %>
@@ -54,7 +54,7 @@
<%= link_to label, path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
<% end %>
<% end %>
<div class="border-t border-slate-100"><%= button_to t(".sign_out"), session_path, method: :delete, class: "block w-full px-4 py-2.5 text-left hover:bg-slate-100", form: { data: { controller: "sign-out", action: "submit->sign-out#clean" } } %></div>
<% unless Viewer.enabled? %><div class="border-t border-slate-100"><%= button_to t(".sign_out"), session_path, method: :delete, class: "block w-full px-4 py-2.5 text-left hover:bg-slate-100", form: { data: { controller: "sign-out", action: "submit->sign-out#clean" } } %></div><% end %>
</div>
</details>
</nav>
@@ -78,9 +78,9 @@
</details>
<% end %>
<%= link_to t(".help"), help_path, class: "hover:text-sky-300" %>
<%= link_to current_user.display_name, edit_profile_path, class: "text-white/70 hover:text-sky-300 hidden sm:inline" %>
<% unless Viewer.enabled? %><%= link_to current_user.display_name, edit_profile_path, class: "text-white/70 hover:text-sky-300 hidden sm:inline" %><% end %>
<%= render "shared/theme_toggle" %>
<%= button_to t(".sign_out"), session_path, method: :delete, class: "rounded bg-white/10 px-2 py-1 hover:bg-white/20", form: { data: { controller: "sign-out", action: "submit->sign-out#clean" } } %>
<% unless Viewer.enabled? %><%= button_to t(".sign_out"), session_path, method: :delete, class: "rounded bg-white/10 px-2 py-1 hover:bg-white/20", form: { data: { controller: "sign-out", action: "submit->sign-out#clean" } } %><% end %>
</nav>
<% end %>
</div>
@@ -92,6 +92,13 @@
</div>
<div class="hidden space-y-1 bg-amber-50 px-4 py-2 text-center text-sm text-amber-900 ring-1 ring-amber-200" data-offline-sync-target="banner" role="status"></div>
<% if Viewer.enabled? %>
<%# Viewer mode: a read-only copy of a records package's archive (see Viewer). %>
<% info = Viewer.info %>
<div class="bg-sky-50 px-4 py-2 text-center text-sm text-sky-900 ring-1 ring-sky-200" role="note" id="viewer-banner">
<%= info ? t("viewer.banner", file: info["file"], date: (info["exported_at"] ? fmt_date(Time.zone.parse(info["exported_at"])) : t("viewer.unknown_date"))) : t("viewer.banner_no_archive") %>
</div>
<% end %>
<main id="main" tabindex="-1" class="mx-auto max-w-7xl px-4 py-6 focus:outline-none">
<%= render "shared/flash" %>
<%= yield %>