makearmy/le-app
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
le-app/docs/le-app-database-migration/implementation-plan.md

7 KiB
Raw Blame History

Laser Everything database transition implementation plan

Status: revised pre-implementation plan. Work stops at the Milestone 0 host-runtime approval gate.

Milestone 0 — complete reproducible application environment

  1. Accepted architecture record

    • Preserve baseline 4884b5d, dedicated Payload service, PostgreSQL, exact dependency matrix, mixed ID preservation, and committed-migration workflow.
    • Review architecture-proposal.md, environment-parity.md, and host prerequisites.

  2. Host runtime gate — requires human approval/provisioning

    • Preserve the completed inert le_app_codex Phase 1 identity/workspace; do not rerun bootstrap artifacts.
    • Preserve the provisional Path A selection: prepare a scheduled complete Arch host upgrade, but require separate approval for the final transaction and reboot; never perform a partial Arch upgrade or install the unmodified AUR extras package.
    • Use a version-matched, checksum-pinned Moby launcher and a genuine per-user Docker service managed through root-controlled user@1200.service; never enable lingering or run dockerd from a system service with User=le_app_codex.
    • Apply containment and the proposed user-1200.slice limits to the complete user manager; accept only unix:///run/user/1200/docker.sock.
    • Create an IPv4-only root-owned namespace with default-deny egress and explicit host/LAN/WireGuard/metadata/private/loopback/bridge/SMTP/IPv6 denial after DNS and complete address inventories are approved.
    • Restrict production environment files currently readable to sol6_vi; verify the development account cannot traverse production paths.
    • Use deterministic CPU BGBye initially; defer optional rootless GPU provisioning.
    • Approve browser-profile-scoped local CA trust for HTTPS testing.
    • Resolve authentication and disk-quota policy separately; confirm nonproduction storage/capacity locations.
    • Use the refreshed post-NoMachine 220-package checksummed baseline; require exact disposition of the reviewed 234 DrKonqi desktop crash-processing failures and hard-stop on any fingerprint change or other failed unit.
    • Verify the repaired /.snapshots Btrfs subvolume and create, number, and independently verify an explicit pre-upgrade Snapper snapshot; do not enable Btrfs quotas or treat unavailable quota accounting as snapshot failure.
    • Execute every inert positive and negative preflight in host-runtime-plan.md before starting the user manager, Docker, Codex, or application work.

  3. Reversible canonical-path consolidation — separately approval-gated

    • Inventory the transitional Git roots, symlinks, credential filenames, rootful disposable containers, and volumes without reading secret values.
    • Create the sole checkout at /srv/le-app-codex/lasereverything.net.db and verify migration/le-app-database commit/remote state.
    • Copy and checksum the scrubbed source into root-owned read-only /srv/le-app-codex/database-source-readonly.
    • Create new nonproduction-only secrets and rootless MariaDB/PostgreSQL resources; do not reuse production credentials.
    • Preserve all old resources through the rollback period. Delete nothing without a later explicit approval.

  4. Repository/environment structure

    • Add common Compose core, mode overlays/profiles, environment schemas/examples, proxy configuration, health contracts, and safe defaults.
    • Complete Docker/build-context exclusions for every context.
    • Add one-command wrappers with context/path/project safety checks.
    • Add automated external-SMTP denial and forbidden-mount/context tests; make snapshot startup fail closed.

  5. Fixture stack

    • Build exact pinned images under Node 24.18.0.
    • Bring up proxy, frontend, Payload shell, PostgreSQL, Mailpit, deterministic CPU BGBye profile, and fixtures.
    • Prove HTTPS cookies, forwarded headers, uploads, mail capture, health, logs, reset, and teardown.

  6. Snapshot/rehearsal stack

    • Mount only authorized scrubbed source and uploads read-only on finite jobs.
    • Add disposable destination media/PostgreSQL and detailed-report exclusions.
    • Add isolated legacy Directus reference profile using a writable clone and local-only credentials.
    • Prove no production SMTP/OAuth/webhook/token configuration or outbound delivery.
    • Keep authoritative source and .migration.env mounted only on finite inventory/import/validation jobs.

  7. Milestone 0 acceptance

    • Clean-checkout fixture startup and smoke test require no undocumented steps.
    • Snapshot startup passes mount/secret/egress safety assertions.
    • Same image digests run in fixture and snapshot modes.
    • Rootless user can control only its nonproduction project resources.
    • Production release dry-run proves a clean reviewed commit and immutable digests deploy only from /var/www/lasereverything.net.db.

Milestone 1 — structural inventory and mapping

  • Generate structural-only collections, fields, relationships, indexes, policies, permissions, flows, operations, row counts, and application-consumer inventory.
  • Commit reviewed field-by-field MariaDB-to-PostgreSQL mapping without record samples.
  • Classify all files and Directus metadata; retain unresolved files.
  • Record only genuine product decisions.

Milestone 2 — Payload schema and security model

  • Implement collections, custom IDs, indexes, relationships, media, users, roles, access functions, hooks, and jobs.
  • Prototype with schema push only on disposable development PostgreSQL.
  • Replace push with committed deterministic migrations before authoritative rehearsal.
  • Implement captured email recovery/verification and shared cookie/session contract.

Milestone 3 — deterministic migration pipeline

  • Implement separate reset, schema, import, and validation jobs.
  • Import in dependency order with preserved IDs/timestamps/ownership and repaired sequences.
  • Preserve password hashes for compatibility research without logging them.
  • Copy referenced media and retain/classify all unreferenced files.
  • Make imports restartable/idempotent or fail safely with explicit checkpoints.

Milestone 4 — application compatibility and end-to-end behavior

  • Move each Directus consumer behind shared Payload/compatibility clients.
  • Rebuild Ko-fi, claims, memberships, flows, and backfill behavior.
  • Implement API contract comparisons and the full fixture/snapshot test matrix.
  • Validate password-hash transitional login and forced rehash strategy.

Milestone 5 — full rehearsals and staging candidate

  • Run repeated clean destination rehearsals.
  • Verify counts, IDs, relationships, timestamps, ownership, permissions, files, checksums, API behavior, and browser workflows.
  • Produce aggregate/non-personal validation summaries and unresolved product decisions.
  • Build immutable release images and promote their digests to staging.

Production boundary

Stop for explicit authorization before production deployment, reverse-proxy/DNS changes, production secrets or SMTP use, email to real users, final write freeze/cutover, Directus restart/retirement, production database mutation, or archive destruction.