[amar-python]

Refs #60, the 15 Nov offline-install commitment. It doesn't close #60: the clean-VM dry run is still needed.

What's added

• scripts/offline/build_bundle.sh. Runs on a connected Ubuntu 24.04 machine and builds one .tar.gz containing:
  • the app source;
  • CPython 3.12 wheels;
  • the frontend, built for a plain Node server (NITRO_PRESET=node-server; the default build targets Cloudflare);
  • Ubuntu packages for PostgreSQL 16, python3.12-venv and Node.js, with an index so apt can use the folder as a local repository;
  • a checksum for every file.
• scripts/offline/install.sh. Runs on the offline VM and installs from the bundle alone. It:
  • checks the checksums;
  • installs packages with the bundle as apt's only source;
  • builds a venv without network access;
  • deploys te_mgmt_prod with its app role and a generated password;
  • writes a mode-600 env file with a generated API key;
  • sets up systemd units for the API (port 8000) and frontend (port 3000);
  • runs the smoke test.
• scripts/offline/smoke_test.sh. Five PASS/FAIL checks: health; a missing key returns 401; a CSV upload inserts 2 rows; the persisted counts are listed; the frontend serves the app. It can be re-run.
• docs/offline-install.md. The procedure, the evidence to attach to 2026-11-15: ship air-gapped install procedure or keep interim wording #60, the known limits, and how the rehearsal was done.
• README: the offline-install limitation now points to the doc and says the VM dry run is still to do. The "fully offline" wording is not switched.

Rehearsal (Claude's Ubuntu 24.04 workspace)

I ran install.sh end to end inside a Linux network namespace with loopback only. curl https://pypi.org returned 000 there.

Step	Result
Bundle checksums	468 files OK
Packages	installed from the bundle's local apt repository
Python environment	venv built from wheels
Database	te_mgmt_prod deployed with 12 te_prod tables
Services	both started
install.sh	exit 0
Smoke test	5/5 PASS, then 5/5 twice more against the running install

What differed from a real VM: systemd was replaced by a stand-in that starts each unit's ExecStart as its User, and PostgreSQL 16 was already installed in the workspace (Node.js was installed from the bundle).

Problems the rehearsal caught and fixed:

• apt pulled in a recommended package (nodejs-doc) that wasn't in the bundle.
• apt can't install loose .deb files offline ("Pathname to install is not absolute"), so the bundle now ships as a local repository.
• The smoke test reused identical content, so a second run was rejected as a duplicate.

The final commit differs from the rehearsed bundle only in that smoke-test fix and the docs.

Checks on this branch

• DB-free pytest: 122 passed.
• scripts/lint.sh: clean.
• bash -n on all three scripts: clean.

Known limits (also in the doc)

• The frontend still sends the shared API key from the browser, until M2 (M2a: control schema and local accounts (BR-36) #92, M2e: frontend sign-in and tenant-scoped session (BR-36) #96).
• The API address is fixed at install.
• Ubuntu 24.04 x86_64 only.
• Fresh VM only.

---

Generated by Claude Code