Spaces:
Running
Running
Deploy Aureon OS (deploy/selfhost stack: nginx edge + fusion API x2 + console + HNC organ + redis + postgres; paper mode) (part 19)
da0ce7b verified | # Aureon website release tooling | |
| This directory is the single automated release stack for the static site in | |
| [`website/`](../../website/): | |
| `audit -> commit-bound build -> fresh backup gate -> non-pruning FTPS upload -> exact read-back` | |
| An upload is not publication proof. The release is complete only when the | |
| read-back comparison passes for the exact package. | |
| ## 1. Audit | |
| ```powershell | |
| python -m scripts.website.audit_site --root website | |
| ``` | |
| The deterministic audit fails on broken internal links/assets, invalid JSON or | |
| JSON-LD, sitemap/canonical drift, and the static accessibility/SEO contracts it | |
| implements. It is not a substitute for the separate claim, browser, a11y, or | |
| Core Web Vitals gates. | |
| ## 2. Build an exact release | |
| The source commit is mandatory. In a Git worktree it must equal checked-out | |
| `HEAD`, and the bounded `website/` tree must be clean. An uncommitted public file | |
| cannot be described as belonging to a commit. | |
| ```powershell | |
| $sourceCommit = (git rev-parse HEAD).Trim() | |
| python -m scripts.website.build_package ` | |
| --root website ` | |
| --out artifacts/website-releases ` | |
| --source-commit $sourceCommit | |
| ``` | |
| The build writes: | |
| - `website_package/` with `index.html` at its root; | |
| - `website_package/HOMEPL_PACKAGE_MANIFEST.txt`, which names the exact source | |
| commit and package contract; | |
| - `website_package/HOMEPL_FILE_HASHES.json`, a sorted SHA-256 record for every | |
| other package file, including the summary manifest; | |
| - `aureon-zorza-website.zip`, produced with deterministic ordering and | |
| timestamps; and | |
| - `aureon-zorza-website.zip.sha256.txt`, the external companion containing the | |
| ZIP hash and the hash of `HOMEPL_FILE_HASHES.json`. | |
| `HOMEPL_FILE_HASHES.json` intentionally excludes itself to avoid recursive | |
| self-hashing. Its own SHA-256 is in the external companion. | |
| For byte-identical reproduction, also pass the same `--created-at` value. A | |
| standalone test fixture outside Git can build with an explicit valid commit, but | |
| the manifest labels that binding `declared-only-isolated-source`; a real | |
| repository build is labelled `verified-git-head-clean-site`. | |
| ## 3. Create and verify a fresh backup | |
| Before any remote write, map the authenticated Home.pl served root and create a | |
| fresh recursive backup with a non-zero manifest. The audited backup tool is | |
| [`website/backup-homepl-ftps.ps1`](../../website/backup-homepl-ftps.ps1). It | |
| emits an `aureon.homepl-backup-transfer.v1` receipt only after a complete, | |
| read-only transfer and manifest verification. | |
| Do not assume that the root is `/` or `/public_html`. The exact current provider | |
| mapping controls. If the existing backup tool's strict root/preflight contract | |
| does not match the current provider mapping, stop and use the Home.pl provider | |
| backup as a named human host gate; do not weaken the mapping check or fabricate | |
| a receipt. | |
| ## 4. Plan and deploy without pruning | |
| The Python deployer and the audited PowerShell tools use one environment-name | |
| contract: | |
| | Variable | Required | Meaning | | |
| |---|---:|---| | |
| | `HOMEPL_FTPS_HOST` | yes | FTPS hostname only | | |
| | `HOMEPL_FTPS_USER` | yes | temporary or approved FTPS account | | |
| | `HOMEPL_FTPS_PASSWORD` | yes | process-only secret; never logged | | |
| | `HOMEPL_FTPS_REMOTE_ROOT` | yes | exact authenticated served root | | |
| | `HOMEPL_FTPS_PORT` | yes | exact authenticated port; never inferred from mode | | |
| | `HOMEPL_FTPS_MODE` | yes | exactly `explicit` or `implicit` | | |
| | `HOMEPL_FTPS_CERT_THUMBPRINT` | PowerShell only | optional pinned certificate thumbprint | | |
| Retained Home.pl configuration evidence points to implicit FTPS on port 990. | |
| The Python uploader supports that transport and explicit FTPS as two separate, | |
| fail-closed modes. Both use the operating system trust store with certificate | |
| and hostname verification and require `PROT P`; implicit mode wraps the control | |
| socket before reading the server welcome and never sends `AUTH TLS`, while | |
| explicit mode negotiates TLS after the welcome. Mode and port remain mandatory | |
| and are never inferred from one another. The exact provider hostname, served | |
| root, and approved credentials are still unresolved operator gates, and no live | |
| Home.pl connection or publication is claimed here. Do not silently substitute | |
| explicit port 21. | |
| Dry-run still requires the target binding and process-only credentials because | |
| it prints the exact authenticated-account plan, but it performs no network | |
| operation: | |
| ```powershell | |
| python -m scripts.website.ftp_deploy ` | |
| --package artifacts/website-releases/website_package ` | |
| --dry-run | |
| ``` | |
| A live upload additionally requires the fresh backup transfer receipt: | |
| ```powershell | |
| python -m scripts.website.ftp_deploy ` | |
| --package artifacts/website-releases/website_package ` | |
| --backup-receipt C:\absolute\path\to\backup-transfer.json | |
| ``` | |
| The deployer verifies the local package against its per-file manifest before | |
| opening a connection. It also verifies that the backup receipt was produced by | |
| the checked `website/backup-homepl-ftps.ps1`, that its deterministic CSV | |
| `Path,Bytes,Sha256` manifest matches the exact downloaded directory, and that | |
| its counts, byte totals, root and freshness agree. A hand-authored receipt or a | |
| manifest detached from the backed-up files is refused. The deployer | |
| creates/overwrites package files only. Pruning and remote deletion are disabled; | |
| `--prune` is always refused. | |
| ## 5. Compare exact read-back | |
| Capture the served-root files through the authenticated operator or fetch the | |
| public paths into an isolated directory, then compare without credentials or | |
| network access: | |
| ```powershell | |
| python -m scripts.website.readback ` | |
| --package artifacts/website-releases/website_package ` | |
| --readback-dir C:\absolute\path\to\captured-served-root | |
| ``` | |
| The directory helper verifies `HOMEPL_FILE_HASHES.json` itself, every listed file | |
| by size and SHA-256, and the absence of unexpected files in the downloaded | |
| served-root mirror. This exact-mirror rule prevents a mixed release from passing | |
| when non-pruning upload leaves stale public files. | |
| `compare_http_observations()` verifies every expected package path from already | |
| captured status/body objects. It cannot discover an unknown stale URL that was | |
| not requested, so it is expected-path evidence, not proof of an exact served-root | |
| file set. Reports never contain bodies, URLs, headers, cookies, or credentials. | |
| TLS, cache headers, public route rendering, visual regression, accessibility, | |
| claim lint, and Core Web Vitals remain separate mandatory release evidence. | |
| ## Manual provider alternatives | |
| Home.pl WebFTP ZIP upload/unzip is a manual host-gate alternative, not a second | |
| release stack. It must use the exact audited ZIP, the same fresh backup gate, | |
| the exact served root, and the same per-file read-back comparison. The legacy | |
| `website/publish-homepl-ftps.ps1` CSV flow and | |
| `website/build-homepl-package.ps1` are not the canonical V45 automated path. | |
| Do not mix their legacy manifests with `HOMEPL_FILE_HASHES.json`. | |
| ## Focused verification | |
| ```powershell | |
| $env:PYTHONDONTWRITEBYTECODE = '1' | |
| python -m pytest -p no:cacheprovider tests/test_website_tooling.py -q | |
| python -m ruff check scripts/website tests/test_website_tooling.py | |
| python -m mypy --strict scripts/website/build_package.py scripts/website/ftp_deploy.py scripts/website/readback.py | |
| ``` | |