Compare commits
15
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a726df5b7c | ||
|
|
9d15d86613 | ||
|
|
6193409838 | ||
|
|
36aa23c4b3 | ||
|
|
db8422afda | ||
|
|
c5c6ec1453 | ||
|
|
158d21ca04 | ||
|
|
86e548f2fc | ||
|
|
3293472cad | ||
|
|
864100b813 | ||
|
|
9971a63635 | ||
|
|
9c29bfcd86 | ||
|
|
8588b058c5 | ||
|
|
d7e19bd9da | ||
|
|
a00fad5553 |
@@ -1,19 +0,0 @@
|
|||||||
**/bin
|
|
||||||
**/obj
|
|
||||||
**/node_modules
|
|
||||||
**/dist
|
|
||||||
.git
|
|
||||||
.env
|
|
||||||
.env.*
|
|
||||||
**/keys
|
|
||||||
tests
|
|
||||||
*.tar*
|
|
||||||
**/pms.local.json
|
|
||||||
|
|
||||||
**/payments.local.json
|
|
||||||
.guestops-maintenance.lock
|
|
||||||
.guestops-test-keyring
|
|
||||||
**/__pycache__
|
|
||||||
*.tar.gpg
|
|
||||||
guestops-backup-*
|
|
||||||
guestops-restore-*
|
|
||||||
+16
-22
@@ -1,22 +1,16 @@
|
|||||||
# Generate separate 32-byte hex values with: openssl rand -hex 32
|
# Native .NET configuration. Keep real credentials out of source control.
|
||||||
# Keep .env private (chmod 600). Never commit real values.
|
Mongo__ConnectionString=mongodb://127.0.0.1:27017
|
||||||
MONGO_ROOT_PASSWORD=
|
Mongo__Database=guestops
|
||||||
MONGO_APP_PASSWORD=
|
Keys__Path=./keys
|
||||||
GOOGLE_CLIENT_ID=
|
PublicUrl=https://sandbox-guestops.futuresens.co.uk
|
||||||
GOOGLE_CLIENT_SECRET=
|
AllowedHosts=sandbox-guestops.futuresens.co.uk;localhost;127.0.0.1
|
||||||
GOOGLE_ENABLE_SENDING=false
|
Proxy__KnownAddress=127.0.0.1
|
||||||
# Only API service needs the AI key. AI remains off per hotel until owner opts in.
|
Google__ClientId=
|
||||||
AI_API_KEY=
|
Google__ClientSecret=
|
||||||
AI_MODEL=
|
Google__EnableSending=false
|
||||||
# Optional private host-side JSON file binding internal hotel IDs to OHIP credentials.
|
Ai__ApiKey=
|
||||||
# Default example has no connections. Never commit the real configuration.
|
Ai__Model=
|
||||||
PMS_CONFIG_FILE_HOST=./deploy/pms.example.json
|
AutoReply__EnableLive=false
|
||||||
# CI produces image archives. Set these to the loaded, reviewed commit tags.
|
# Optional private files. Leave unset to disable PMS and payment integrations.
|
||||||
GUESTOPS_API_IMAGE=guestops-api:local
|
Pms__ConfigFile=
|
||||||
GUESTOPS_WORKER_IMAGE=guestops-worker:local
|
Payments__ConfigFile=
|
||||||
|
|
||||||
# Private NMI configuration; leave the empty example until sandbox setup.
|
|
||||||
PAYMENTS_CONFIG_FILE_HOST=./deploy/payments.example.json
|
|
||||||
|
|
||||||
# Enable only after Google delivery and FAQ test-mode acceptance.
|
|
||||||
AUTO_REPLY_ENABLE_LIVE=false
|
|
||||||
|
|||||||
@@ -1,98 +0,0 @@
|
|||||||
name: Build and verify web migration
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [main, 'codex/**']
|
|
||||||
tags: ['[0-9]+.[0-9]+.[0-9]+']
|
|
||||||
pull_request:
|
|
||||||
workflow_dispatch:
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
jobs:
|
|
||||||
verify:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
services:
|
|
||||||
mongo:
|
|
||||||
image: mongo:8.0
|
|
||||||
ports: ['27017:27017']
|
|
||||||
options: >-
|
|
||||||
--health-cmd "mongosh --quiet --eval 'db.adminCommand({ping:1}).ok'"
|
|
||||||
--health-interval 10s --health-timeout 5s --health-retries 10
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- uses: actions/setup-dotnet@v4
|
|
||||||
with: { dotnet-version: '10.0.x' }
|
|
||||||
- uses: actions/setup-node@v4
|
|
||||||
with: { node-version: '22', cache: npm, cache-dependency-path: web/package-lock.json }
|
|
||||||
- name: Build services
|
|
||||||
run: dotnet build src/GuestOps.Worker/GuestOps.Worker.csproj -c Release
|
|
||||||
- name: Verify backup validation and failure recovery
|
|
||||||
run: python3 -m unittest discover -s tests -p 'test_*.py'
|
|
||||||
- name: Build interface
|
|
||||||
working-directory: web
|
|
||||||
run: npm ci && npm run build
|
|
||||||
- name: Start isolated preview API
|
|
||||||
run: |
|
|
||||||
ASPNETCORE_ENVIRONMENT=Development Preview=true dotnet src/GuestOps.Api/bin/Release/net10.0/GuestOps.Api.dll --urls http://127.0.0.1:5180 > /tmp/guestops-api.log 2>&1 &
|
|
||||||
for i in $(seq 1 30); do curl -fsS http://127.0.0.1:5180/health && exit 0; sleep 1; done
|
|
||||||
cat /tmp/guestops-api.log
|
|
||||||
exit 1
|
|
||||||
- name: Verify MongoDB and HTTP boundaries
|
|
||||||
env:
|
|
||||||
MONGO_TEST_URI: mongodb://127.0.0.1:27017
|
|
||||||
TEST_API_URL: http://127.0.0.1:5180
|
|
||||||
run: dotnet run --project tests/GuestOps.Tests/GuestOps.Tests.csproj -c Release
|
|
||||||
- name: Build Linux images
|
|
||||||
run: |
|
|
||||||
docker build --target api -t guestops-api:${{ github.sha }} .
|
|
||||||
docker build --target worker -t guestops-worker:${{ github.sha }} .
|
|
||||||
- name: Package reviewed images
|
|
||||||
if: github.event_name != 'pull_request'
|
|
||||||
run: |
|
|
||||||
docker save guestops-api:${{ github.sha }} guestops-worker:${{ github.sha }} | gzip -n > guestops-images.tar.gz
|
|
||||||
python3 deploy/release_record.py \
|
|
||||||
--artifact guestops-images.tar.gz \
|
|
||||||
--commit '${{ github.sha }}' \
|
|
||||||
--api-image 'guestops-api:${{ github.sha }}' \
|
|
||||||
--api-id "$(docker image inspect --format '{{.Id}}' 'guestops-api:${{ github.sha }}')" \
|
|
||||||
--worker-image 'guestops-worker:${{ github.sha }}' \
|
|
||||||
--worker-id "$(docker image inspect --format '{{.Id}}' 'guestops-worker:${{ github.sha }}')" \
|
|
||||||
--output release-record.json
|
|
||||||
sha256sum --check <(python3 -c "import json; r=json.load(open('release-record.json')); print(r['artifact']['sha256'] + ' ' + r['artifact']['name'])")
|
|
||||||
- name: Smoke test production containers and restart persistence
|
|
||||||
env:
|
|
||||||
GUESTOPS_API_IMAGE: guestops-api:${{ github.sha }}
|
|
||||||
GUESTOPS_WORKER_IMAGE: guestops-worker:${{ github.sha }}
|
|
||||||
BOOTSTRAP_EMAIL: ci-owner@example.invalid
|
|
||||||
BOOTSTRAP_HOTEL: CI test hotel
|
|
||||||
run: |
|
|
||||||
export MONGO_ROOT_PASSWORD=$(openssl rand -hex 32)
|
|
||||||
export MONGO_APP_PASSWORD=$(openssl rand -hex 32)
|
|
||||||
export BOOTSTRAP_PASSWORD=$(openssl rand -hex 24)
|
|
||||||
trap 'docker compose down --volumes' EXIT
|
|
||||||
docker compose config --quiet
|
|
||||||
docker compose up -d --no-build
|
|
||||||
curl --retry 30 --retry-delay 2 --retry-all-errors --fail http://127.0.0.1:8080/health
|
|
||||||
docker compose run --rm --no-deps -e BOOTSTRAP_EMAIL -e BOOTSTRAP_HOTEL -e BOOTSTRAP_PASSWORD api --bootstrap
|
|
||||||
python3 tests/production_smoke.py
|
|
||||||
docker compose restart api worker
|
|
||||||
curl --retry 30 --retry-delay 2 --retry-all-errors --fail http://127.0.0.1:8080/health
|
|
||||||
python3 tests/production_smoke.py --read
|
|
||||||
install -m 600 /dev/null .env
|
|
||||||
python3 deploy/ops.py preflight --offline
|
|
||||||
mkdir -m 700 .guestops-test-keyring
|
|
||||||
export GNUPGHOME="$PWD/.guestops-test-keyring"
|
|
||||||
gpg --batch --pinentry-mode loopback --passphrase '' --quick-generate-key 'GuestOps CI <ci@example.invalid>' rsa2048 encr 1d
|
|
||||||
BACKUP_RECIPIENT=$(gpg --batch --with-colons --list-keys | awk -F: '$1=="fpr" {print $10; exit}')
|
|
||||||
backup_dir=$(mktemp -d)
|
|
||||||
python3 deploy/ops.py backup --recipient "$BACKUP_RECIPIENT" --output "$backup_dir/fixture.tar.gpg" --confirm-maintenance
|
|
||||||
python3 deploy/ops.py restore-drill "$backup_dir/fixture.tar.gpg" --api-image "$GUESTOPS_API_IMAGE"
|
|
||||||
curl --retry 30 --retry-delay 2 --retry-all-errors --fail http://127.0.0.1:8080/health/ready
|
|
||||||
python3 tests/production_smoke.py --read
|
|
||||||
- uses: actions/upload-artifact@v4
|
|
||||||
if: github.event_name != 'pull_request'
|
|
||||||
with:
|
|
||||||
name: guestops-linux-${{ github.run_number }}
|
|
||||||
path: |
|
|
||||||
guestops-images.tar.gz
|
|
||||||
release-record.json
|
|
||||||
retention-days: 90
|
|
||||||
@@ -17,6 +17,7 @@
|
|||||||
**/payments.local.json
|
**/payments.local.json
|
||||||
.guestops-maintenance.lock
|
.guestops-maintenance.lock
|
||||||
.guestops-test-keyring/
|
.guestops-test-keyring/
|
||||||
|
.guestops-release/
|
||||||
guestops-backup-*/
|
guestops-backup-*/
|
||||||
guestops-restore-*/
|
guestops-restore-*/
|
||||||
*.tar.gpg
|
*.tar.gpg
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
<Project>
|
<Project>
|
||||||
<PropertyGroup>
|
<PropertyGroup>
|
||||||
<TargetFramework>net10.0</TargetFramework>
|
<TargetFramework>net10.0</TargetFramework>
|
||||||
<Version>0.2.0</Version>
|
<Version>0.2.2</Version>
|
||||||
<Nullable>enable</Nullable>
|
<Nullable>enable</Nullable>
|
||||||
<ImplicitUsings>enable</ImplicitUsings>
|
<ImplicitUsings>enable</ImplicitUsings>
|
||||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||||
|
|||||||
-31
@@ -1,31 +0,0 @@
|
|||||||
FROM node:22-bookworm-slim AS frontend
|
|
||||||
WORKDIR /build/web
|
|
||||||
COPY web/package*.json ./
|
|
||||||
RUN npm ci --no-audit --no-fund
|
|
||||||
COPY web/ ./
|
|
||||||
RUN npm run build
|
|
||||||
|
|
||||||
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS backend
|
|
||||||
WORKDIR /build
|
|
||||||
COPY Directory.Build.props ./
|
|
||||||
COPY src/ ./src/
|
|
||||||
RUN dotnet publish src/GuestOps.Api/GuestOps.Api.csproj -c Release -o /publish/api
|
|
||||||
RUN dotnet publish src/GuestOps.Worker/GuestOps.Worker.csproj -c Release -o /publish/worker
|
|
||||||
|
|
||||||
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS api
|
|
||||||
WORKDIR /app
|
|
||||||
RUN mkdir -p /var/lib/guestops/keys && chown -R app:app /var/lib/guestops && chmod 700 /var/lib/guestops/keys
|
|
||||||
COPY --from=backend /publish/api ./
|
|
||||||
COPY --from=frontend /build/web/dist ./wwwroot/
|
|
||||||
ENV ASPNETCORE_URLS=http://+:8080 ASPNETCORE_ENVIRONMENT=Production Keys__Path=/var/lib/guestops/keys
|
|
||||||
USER app
|
|
||||||
EXPOSE 8080
|
|
||||||
ENTRYPOINT ["dotnet", "GuestOps.Api.dll"]
|
|
||||||
|
|
||||||
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS worker
|
|
||||||
WORKDIR /app
|
|
||||||
RUN mkdir -p /var/lib/guestops/keys && chown -R app:app /var/lib/guestops && chmod 700 /var/lib/guestops/keys
|
|
||||||
COPY --from=backend /publish/worker ./
|
|
||||||
ENV DOTNET_ENVIRONMENT=Production Keys__Path=/var/lib/guestops/keys
|
|
||||||
USER app
|
|
||||||
ENTRYPOINT ["dotnet", "GuestOps.Worker.dll"]
|
|
||||||
+41
-13
@@ -1,10 +1,36 @@
|
|||||||
# GuestOps Milestone Report
|
# GuestOps Milestone Report
|
||||||
|
|
||||||
Version: **0.2.0 release candidate**
|
Version: **0.2.2 release candidate**
|
||||||
Last updated: **29 September 2026**
|
Last updated: **22 October 2026**
|
||||||
|
|
||||||
This is the working delivery tracker for GuestOps Web. Update a milestone when its state changes and link the pull request, release artifact, test run, or acceptance record that proves the change.
|
This is the working delivery tracker for GuestOps Web. Update a milestone when its state changes and link the pull request, release artifact, test run, or acceptance record that proves the change.
|
||||||
|
|
||||||
|
## Milestones at a glance
|
||||||
|
|
||||||
|
This summary explains what each milestone delivers and where it currently stands. The release-gate and delivery tables below contain the detailed evidence and exit conditions.
|
||||||
|
|
||||||
|
| # | Milestone | What it delivers | Current position |
|
||||||
|
| ---: | --- | --- | --- |
|
||||||
|
| 1 | Web foundation | The React application, ASP.NET Core API, tenant-isolated MongoDB storage, preview mode, and native Linux foundation. | **Implemented.** The application foundation and automated tests are on `main`. |
|
||||||
|
| 2 | AI suggestions and reviewed Gmail sending | AI-assisted reply drafts and staff-reviewed Gmail delivery with safety and duplicate-send controls. | **Implemented; acceptance required.** Real Gmail threading, revocation, uncertain-send, and staff-review scenarios still need live evidence. |
|
||||||
|
| 3 | OHIP PMS workflow | Internal proposal, approval, and execution controls for PMS operations. | **Implemented; acceptance required.** The workflow exists, but provider-contract and sandbox acceptance remain outstanding. |
|
||||||
|
| 4 | NMI payment workflow | Internal payment proposal, approval, status, expiry, and reconciliation controls. | **Implemented; acceptance required.** The workflow exists, but real payment-provider sandbox acceptance remains outstanding. |
|
||||||
|
| 5 | FAQ automation | Knowledge-based FAQ drafting, test mode, approval controls, and guarded live automation. | **Implemented; acceptance required.** Live mode remains disabled pending quality, false-positive, monitoring, and rollback acceptance. |
|
||||||
|
| 6 | Team onboarding and account recovery | Staff invitations, password setup/reset, access disable/restore, and administrator recovery. | **Implemented; acceptance required.** Deployed link delivery, expiry, recovery, and administrator procedures still need operational evidence. |
|
||||||
|
| 7 | Google connection recovery | OAuth reconnect, checkpoint recovery, grant revocation handling, and worker restart safety. | **Implemented; acceptance required.** Dedicated Google-account and worker-restart exercises have not yet been accepted. |
|
||||||
|
| 8 | Operational readiness | Host backup, monitoring, and recovery are provided by the existing central infrastructure. | **External.** GuestOps no longer carries a second application-specific operational stack. |
|
||||||
|
| 9 | Versioned releases | A deterministic version-named native archive and Ansible-controlled installation. | **Implemented; acceptance required.** Package the tested commit as `guestops_<version>.tar.gz` and deploy it through the central playbook. |
|
||||||
|
| 10 | Debian deployment and persistence | Native systemd deployment, HTTPS, local MongoDB, and persistent Data Protection keys. | **In progress.** The single Ansible playbook installs the self-contained API/worker, configures Nginx, restricts the listener and checks public readiness; sandbox deployment remains to be exercised. |
|
||||||
|
| 11 | Backups, monitoring, and recovery | Existing central MongoDB backup, Filebeat, host monitoring, and version-based rollback. | **External.** Rollback selects an older archive and reruns the same deployment playbook. |
|
||||||
|
| 12 | Google mailbox acceptance | End-to-end Gmail consent, import, recovery, reviewed sending, reconciliation, and revocation evidence. | **In progress.** The runbook, record validator and release-bound Gate B bundle integration exist; the live synthetic-data exercise and independent review remain outstanding. |
|
||||||
|
| 13 | Rezlynx/Guestline adapter | The real PMS provider adapter, mappings, idempotency, reconciliation, and ambiguous-write handling. | **Planned.** Provider contract and sandbox access are still required before implementation and acceptance. |
|
||||||
|
| 14 | Payment links and status | The real payment-provider integration, webhooks, expiry, replay protection, and reconciliation. | **Planned.** The provider path and sandbox acceptance plan still need to be confirmed and completed. |
|
||||||
|
| 15 | Knowledge, AI, and FAQ activation | Supervised knowledge-quality, AI-draft, FAQ test-mode, staff-training, and stop-control acceptance. | **Implemented; acceptance required.** Evaluation tooling and cross-release bundle validation exist; the supervised evaluation, staff training and independent approval remain outstanding. |
|
||||||
|
| 16 | Identity, preferences, and privacy | Account/session controls, hotel preferences, privacy inventory, retention decisions, and audit review. | **Implemented; acceptance required.** Legal and operational decisions, identity checks, and independent review remain outstanding. |
|
||||||
|
| 17 | Inbox usability and desktop parity | Stable pagination, protected unsaved drafts, hotel-timezone display, and desktop workflow parity. | **Implemented; acceptance required.** Automated checks pass; the supervised desktop exercise and independent approval remain outstanding. |
|
||||||
|
| 18 | Pilot, capacity, and release approval | Capacity proof, incident exercise, five-business-day hotel pilot, findings closure, and Gate B approval. | **In progress.** Live prerequisites, incident rehearsal, five-day pilot and named approvals remain open. |
|
||||||
|
| 19 | Account security and self-service | TOTP MFA, recovery codes, transactional email, granular roles, preferences, and security notifications. | **Implemented on the development branch; acceptance required.** Keep it separate until `0.2.2` is approved and tagged, then review, merge, and version it as `0.3.0`. |
|
||||||
|
|
||||||
## Status key
|
## Status key
|
||||||
|
|
||||||
- **Implemented** — present on `main` and supported by code or automated-test evidence.
|
- **Implemented** — present on `main` and supported by code or automated-test evidence.
|
||||||
@@ -25,24 +51,24 @@ This is the working delivery tracker for GuestOps Web. Update a milestone when i
|
|||||||
|
|
||||||
| # | Milestone | Gate | Status | Evidence and remaining work |
|
| # | Milestone | Gate | Status | Evidence and remaining work |
|
||||||
| ---: | --- | :---: | --- | --- |
|
| ---: | --- | :---: | --- | --- |
|
||||||
| 1 | Web foundation | A | Implemented | The current `main` branch provides the React workspace, ASP.NET Core API, tenant-scoped MongoDB access, read-only Google import foundation, preview mode, container definitions, and automated tests. Live provider and host acceptance still apply. |
|
| 1 | Web foundation | A | Implemented | The current `main` branch provides the React workspace, ASP.NET Core API, tenant-scoped MongoDB access, read-only Google import foundation, preview mode, native Linux packaging, and automated tests. Live provider and host acceptance still apply. |
|
||||||
| 2 | AI suggestions and reviewed Gmail sending | B | Implemented / acceptance required | Promoted to local `main`; verify real mailbox threading, reconnect/revocation, duplicate-send prevention, uncertain outcomes, and staff review before pilot use. |
|
| 2 | AI suggestions and reviewed Gmail sending | B | Implemented / acceptance required | Promoted to local `main`; verify real mailbox threading, reconnect/revocation, duplicate-send prevention, uncertain outcomes, and staff review before pilot use. |
|
||||||
| 3 | OHIP PMS workflow | C | Implemented / acceptance required | Proposal, approval, and execution controls are promoted to local `main`. Provider sandbox and contract-level acceptance remain independent requirements. |
|
| 3 | OHIP PMS workflow | C | Implemented / acceptance required | Proposal, approval, and execution controls are promoted to local `main`. Provider sandbox and contract-level acceptance remain independent requirements. |
|
||||||
| 4 | NMI payment workflow | C | Implemented / acceptance required | Payment proposal and approval controls are promoted to local `main`. Sandbox acceptance, reconciliation, expiry, and ambiguous-result recovery remain required. |
|
| 4 | NMI payment workflow | C | Implemented / acceptance required | Payment proposal and approval controls are promoted to local `main`. Sandbox acceptance, reconciliation, expiry, and ambiguous-result recovery remain required. |
|
||||||
| 5 | FAQ automation | B | Implemented / acceptance required | Draft and approval controls are promoted to local `main`. Keep live automation disabled until knowledge quality, thresholds, and rollback behaviour pass acceptance. |
|
| 5 | FAQ automation | B | Implemented / acceptance required | Draft and approval controls are promoted to local `main`. Keep live automation disabled until knowledge quality, thresholds, and rollback behaviour pass acceptance. |
|
||||||
| 6 | Team onboarding and account recovery | B | Implemented / acceptance required | Invitation, password reset, and recovery flows are promoted to local `main`; verify deployed links, mail delivery, token expiry, and administrator recovery procedures. |
|
| 6 | Team onboarding and account recovery | B | Implemented / acceptance required | Invitation, password reset, and recovery flows are promoted to local `main`; verify deployed links, mail delivery, token expiry, and administrator recovery procedures. |
|
||||||
| 7 | Google connection recovery | B | Implemented / acceptance required | Connection epochs, checkpoint recovery, and revocation handling are promoted to local `main`; complete real Google acceptance and worker-restart exercises. |
|
| 7 | Google connection recovery | B | Implemented / acceptance required | Connection epochs, checkpoint recovery, and revocation handling are promoted to local `main`; complete real Google acceptance and worker-restart exercises. |
|
||||||
| 8 | Operational readiness tooling | A | Implemented / acceptance required | Backup, restore, release, and diagnostic tooling is promoted to local `main`; execute it on the actual Debian host and retain evidence. |
|
| 8 | Operational readiness tooling | A | External | Use the existing host backup, Filebeat, monitoring and recovery processes instead of a second GuestOps-specific operational stack. |
|
||||||
| 9 | Gitea and reproducible releases | A | In progress | The `0.2.0` candidate is versioned on `main`. CI records the full commit, matched application version, archive checksum and immutable image IDs, and the rollback procedure is documented. Retain the successful default-branch evidence off-host and create the immutable approval tag only after Gate B approval; the existing `0.1.0` tag remains attached to the foundation release. |
|
| 9 | Gitea and versioned releases | A | In progress | `deploy/package_release.py` builds an explicit committed ref as an immutable self-contained Linux x64 `guestops_<version>.tar.gz`, verifies matching .NET/frontend versions, and refuses overwrite. Deploy it through the central version-selected Ansible playbook. |
|
||||||
| 10 | Debian deployment and persistence | A | In progress | Compose uses separate named database and shared key volumes, private host configuration, loopback-only API access and bounded logs. The confirmation-gated persistence drill verifies restart and container-recreation behaviour. Run it on the provisioned Debian host, complete HTTPS and controlled-reboot acceptance, and retain the evidence. |
|
| 10 | Debian deployment and persistence | A | In progress | Native systemd services run the API and worker against local MongoDB, preserve `/var/lib/guestops/keys`, and bind the API to loopback. Exercise the single Ansible playbook on sandbox and confirm a second deployment preserves the keys. |
|
||||||
| 11 | Backups, monitoring, and recovery | A | In progress | Encrypted backup and isolated restore tooling now includes opt-in systemd scheduling without command-line secrets. Install and test it on Debian, configure monitored off-host transfer and durable logs, name alert/retention owners, and retain evidence from a timed restore and recovery drill. |
|
| 11 | Backups, monitoring, and recovery | A | External | The existing central MongoDB backup, Filebeat, host monitoring and archive retention remain authoritative. Rollback selects an earlier GuestOps version and reruns the deployment playbook. |
|
||||||
| 12 | Google mailbox and reviewed-reply acceptance | B | In progress | The synthetic-data provider runbook, exact scenario set and restricted-record validator are implemented. Complete every scenario against the accepted Debian release and dedicated Google sandbox accounts, independently review the evidence, and retain the validated record. |
|
| 12 | Google mailbox and reviewed-reply acceptance | B | In progress | The synthetic-data provider runbook, exact scenario set and restricted-record validator are implemented and wired into the Gate B bundle validator. Complete every scenario against the accepted Debian release and dedicated Google sandbox accounts, independently review the evidence, and retain the validated record. |
|
||||||
| 13 | Rezlynx/Guestline adapter | C | Planned | Obtain the provider contract and sandbox, implement the adapter and mapping, and accept idempotency, stale-data, ambiguous-write, and reconciliation paths. |
|
| 13 | Rezlynx/Guestline adapter | C | Planned | Obtain the provider contract and sandbox, implement the adapter and mapping, and accept idempotency, stale-data, ambiguous-write, and reconciliation paths. |
|
||||||
| 14 | Payment links and status | C | Planned | Select/confirm the payment-provider path, complete sandbox and webhook acceptance, and prove expiry, replay protection, reconciliation, and support recovery. |
|
| 14 | Payment links and status | C | Planned | Select/confirm the payment-provider path, complete sandbox and webhook acceptance, and prove expiry, replay protection, reconciliation, and support recovery. |
|
||||||
| 15 | Knowledge, AI, and FAQ activation | B | Implemented / acceptance required | Owners can run a bounded no-send batch evaluation, and a release-bound acceptance record enforces positive/negative coverage, zero FAQ errors, separate AI review, staff training, stop-control evidence and named monitoring/rollback owners. Complete the supervised evaluation and retain independent approval. |
|
| 15 | Knowledge, AI, and FAQ activation | B | Implemented / acceptance required | Owners can run a bounded no-send batch evaluation, and a release-bound acceptance record enforces positive/negative coverage, zero FAQ errors, separate AI review, staff training, stop-control evidence and named monitoring/rollback owners. The integrated Gate B bundle rejects release or environment mismatches. Complete the supervised evaluation and retain independent approval. |
|
||||||
| 16 | Identity, preferences, and privacy | B/C | Implemented / acceptance required | Login throttling trusts the client address only after one-hop processing by the configured proxy. A release-bound review now covers owner-controlled preferences, account/session controls, data inventory, retention/deletion/legal-hold ownership, provider decisions, audit evidence and known identity limitations. Complete the legal/operational decisions and independently approve the record. |
|
| 16 | Identity, preferences, and privacy | B/C | Implemented / acceptance required | Login throttling trusts the client address only after one-hop processing by the configured proxy. A release-bound review now covers owner-controlled preferences, account/session controls, data inventory, retention/deletion/legal-hold ownership, provider decisions, audit evidence and known identity limitations. Complete the legal/operational decisions and independently approve the record. |
|
||||||
| 17 | Inbox usability and desktop parity | B | Implemented / acceptance required | The inbox uses tenant-scoped stable cursor pagination in pages of 50 and protects unsaved drafts during route/history navigation, reload, conversation selection, filtering and search. Operational timestamps use the saved hotel timezone, and a release-bound desktop-parity acceptance record is implemented. The implementation and preview HTTP suite pass; run the supervised exercise against the approved release and retain independent approval. |
|
| 17 | Inbox usability and desktop parity | B | Implemented / acceptance required | The inbox uses tenant-scoped stable cursor pagination in pages of 50 and protects unsaved drafts during route/history navigation, reload, conversation selection, filtering and search. Operational timestamps use the saved hotel timezone, and a release-bound desktop-parity acceptance record is implemented. The implementation and preview HTTP suite pass; run the supervised exercise against the approved release and retain independent approval. |
|
||||||
| 18 | Pilot, capacity, and release approval | B/C | In progress | The `0.2.0` Gate B candidate has bounded capacity, five-business-day pilot, incident and final-decision record validators with agreed targets. Push and retain CI evidence, complete Gate A and Gate B prerequisites, run the probe and supervised exercises, resolve or contain findings, and retain separate hotel-owner and technical approval. Gate C remains dependent on milestones 13 and 14. |
|
| 18 | Pilot, capacity, and release approval | B/C | In progress | Complete the live Gate A/B exercises against the selected version, resolve or contain findings, and retain separate hotel-owner and technical approval. Gate C remains dependent on milestones 13 and 14. |
|
||||||
|
|
||||||
## Delivery sequence
|
## Delivery sequence
|
||||||
|
|
||||||
@@ -54,10 +80,12 @@ Milestones 13 (Guestline/Rezlynx) and 14 (payments) can progress as parallel pro
|
|||||||
|
|
||||||
## Next actions
|
## Next actions
|
||||||
|
|
||||||
- [ ] Push the local release-candidate promotion to the intended default branch and retain its successful CI evidence.
|
- [ ] Merge the Action removal and release-process update to the intended default branch; that resulting commit becomes the new package candidate.
|
||||||
- [ ] Retain successful `0.2.0` default-branch CI evidence, then create and archive the immutable approval tag only after Gate B approval.
|
- [x] Preserve the published `0.2.0` tag unchanged and use the clean `0.2.2` candidate line from `main`, excluding Milestone 19 application code.
|
||||||
|
- [ ] Create the immutable versioned archive with `deploy/package_release.py`, copy it into the Ansible files directory, and select its version in group vars.
|
||||||
|
- [ ] Create and archive the immutable `0.2.2` approval tag only after Gate B approval.
|
||||||
- [ ] Deploy to the target Debian environment with persistent MongoDB and data-protection keys.
|
- [ ] Deploy to the target Debian environment with persistent MongoDB and data-protection keys.
|
||||||
- [ ] Run and record backup, restore, restart, monitoring, and rollback exercises.
|
- [ ] Confirm the existing central backup and monitoring processes include GuestOps, then test rollback by selecting the previous version.
|
||||||
- [ ] Complete real Google mailbox acceptance without using production guest data.
|
- [ ] Complete real Google mailbox acceptance without using production guest data.
|
||||||
- [ ] Resolve or explicitly contain the milestone 16–17 pilot findings listed above.
|
- [ ] Resolve or explicitly contain the milestone 16–17 pilot findings listed above.
|
||||||
- [ ] Obtain the Guestline/Rezlynx interface contract and sandbox access.
|
- [ ] Obtain the Guestline/Rezlynx interface contract and sandbox access.
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
A Linux-hosted hotel email workspace, developed separately from the Windows GuestOps application. **This migration now includes AI draft generation, staff-approved Gmail sending, reviewed OHIP reservation updates, NMI hosted invoices, controlled FAQ auto-replies and team onboarding. It is not yet a production-complete replacement.**
|
A Linux-hosted hotel email workspace, developed separately from the Windows GuestOps application. **This migration now includes AI draft generation, staff-approved Gmail sending, reviewed OHIP reservation updates, NMI hosted invoices, controlled FAQ auto-replies and team onboarding. It is not yet a production-complete replacement.**
|
||||||
|
|
||||||
Current release-candidate version: **0.2.0**
|
Current release-candidate version: **0.2.2**
|
||||||
|
|
||||||
Project progress is tracked in the [milestone report](MILESTONES.md). User-visible changes and release limitations are recorded in the [release notes](RELEASE_NOTES.md).
|
Project progress is tracked in the [milestone report](MILESTONES.md). User-visible changes and release limitations are recorded in the [release notes](RELEASE_NOTES.md).
|
||||||
|
|
||||||
@@ -19,7 +19,7 @@ Project progress is tracked in the [milestone report](MILESTONES.md). User-visib
|
|||||||
- Controlled FAQ auto-replies: exact plain-text questions, owner-reviewed answers, test mode, daily quotas and thread/knowledge rechecks. Live mode defaults off.
|
- Controlled FAQ auto-replies: exact plain-text questions, owner-reviewed answers, test mode, daily quotas and thread/knowledge rechecks. Live mode defaults off.
|
||||||
- Owner-issued staff invitations, assisted password recovery, session invalidation, disabled-account restoration and a hotel setup checklist. See [team access](docs/accounts.md).
|
- Owner-issued staff invitations, assisted password recovery, session invalidation, disabled-account restoration and a hotel setup checklist. See [team access](docs/accounts.md).
|
||||||
- Google mailbox health, owner-only disconnect/reconnect and import restart, revoked-consent handling, retry delays and connection-bound delivery approvals. See [mailbox management](docs/mailboxes.md).
|
- Google mailbox health, owner-only disconnect/reconnect and import restart, revoked-consent handling, retry delays and connection-bound delivery approvals. See [mailbox management](docs/mailboxes.md).
|
||||||
- Docker image builds, private MongoDB configuration and an Nginx HTTPS example for the Debian sandbox.
|
- Self-contained Linux API and worker releases, native systemd services, local MongoDB configuration and an Nginx HTTPS example for the Debian sandbox.
|
||||||
|
|
||||||
## Explicit limits
|
## Explicit limits
|
||||||
|
|
||||||
@@ -57,7 +57,9 @@ Open http://127.0.0.1:5173 and select **Open preview workspace**. Each preview l
|
|||||||
|
|
||||||
For MongoDB-backed operation, disable Preview and set `Mongo__ConnectionString`, `Mongo__Database`, and a persistent private `Keys__Path`. See [deployment](docs/deployment.md).
|
For MongoDB-backed operation, disable Preview and set `Mongo__ConnectionString`, `Mongo__Database`, and a persistent private `Keys__Path`. See [deployment](docs/deployment.md).
|
||||||
|
|
||||||
Operational tooling includes an owner-only Workspace health page and Linux deployment preflight, encrypted backup and isolated restore drill. See [operations and recovery](docs/operations.md) before the hotel pilot.
|
The owner-only Workspace health page remains available in the application. Host monitoring, MongoDB backup and disaster recovery are provided by the existing central infrastructure.
|
||||||
|
|
||||||
|
Release packaging is runner-free. `deploy/package_release.py` builds an immutable, self-contained Linux x64 `guestops_<version>.tar.gz` archive from one explicit committed Git ref for handoff to the Futuresens Ansible deployment. It never packages uncommitted working-tree files. Target servers need no application build tooling or .NET runtime installation.
|
||||||
|
|
||||||
## Verification
|
## Verification
|
||||||
|
|
||||||
@@ -66,7 +68,7 @@ dotnet run --project tests/GuestOps.Tests
|
|||||||
cd web && npm ci && npm run build
|
cd web && npm ci && npm run build
|
||||||
```
|
```
|
||||||
|
|
||||||
Set `MONGO_TEST_URI` to an isolated MongoDB server and `TEST_API_URL=http://127.0.0.1:5180` with a preview API running to enable database and HTTP integration checks. The suite creates and drops only its own randomly named `guestops_test_*` database. CI runs both integrations and builds both Linux images.
|
Set `MONGO_TEST_URI` to an isolated MongoDB server and `TEST_API_URL=http://127.0.0.1:5180` with a preview API running to enable database and HTTP integration checks. The suite creates and drops only its own randomly named `guestops_test_*` database. Run these checks before creating a versioned release package. GuestOps does not require a Gitea Actions runner; deployment follows the existing Futuresens release-package and Ansible process described in the [deployment guide](docs/deployment.md).
|
||||||
|
|
||||||
See [controlled FAQ automation](docs/auto-replies.md), [NMI payment setup and recovery](docs/payments.md), [OHIP reservation setup and recovery](docs/pms.md), [AI drafts and reply delivery setup](docs/replies.md), [migration status](docs/migration.md) and [deployment guide](docs/deployment.md).
|
See [controlled FAQ automation](docs/auto-replies.md), [NMI payment setup and recovery](docs/payments.md), [OHIP reservation setup and recovery](docs/pms.md), [AI drafts and reply delivery setup](docs/replies.md), [migration status](docs/migration.md) and [deployment guide](docs/deployment.md).
|
||||||
|
|
||||||
|
|||||||
+10
-6
@@ -1,8 +1,8 @@
|
|||||||
# GuestOps Release Notes
|
# GuestOps Release Notes
|
||||||
|
|
||||||
## 0.2.0 — Gate B release candidate
|
## 0.2.2 — Gate B native deployment candidate
|
||||||
|
|
||||||
This candidate freezes the implemented Gate B scope for controlled acceptance. It is not yet approved for live hotel operations and does not become a release until the exact commit is pushed, CI and operational evidence are retained, the supervised pilot is approved and the immutable `0.2.0` tag is created.
|
This candidate freezes the implemented Gate B scope for controlled acceptance and replaces the unsuccessful source-build `0.2.1` deployment artifact with self-contained Linux x64 API and worker applications managed by systemd. It is not yet approved for live hotel operations and does not become a release until the exact commit is pushed, a checksummed native package and operational evidence are retained, the supervised pilot is approved and the immutable `0.2.2` tag is created.
|
||||||
|
|
||||||
### Promoted scope
|
### Promoted scope
|
||||||
|
|
||||||
@@ -13,19 +13,23 @@ This candidate freezes the implemented Gate B scope for controlled acceptance. I
|
|||||||
- Release-bound automation and identity/privacy acceptance records covering training, provider decisions, retention ownership and known limitations.
|
- Release-bound automation and identity/privacy acceptance records covering training, provider decisions, retention ownership and known limitations.
|
||||||
- Stable tenant-scoped inbox pagination beyond the former 500-message view, unsaved-draft guards including browser history navigation, consistent hotel-timezone timestamps across operational screens, and a release-bound desktop-parity acceptance record.
|
- Stable tenant-scoped inbox pagination beyond the former 500-message view, unsaved-draft guards including browser history navigation, consistent hotel-timezone timestamps across operational screens, and a release-bound desktop-parity acceptance record.
|
||||||
- A bounded read-only sandbox capacity probe plus machine-validated, release-bound supervised-pilot run, go/no-go and incident-exercise records.
|
- A bounded read-only sandbox capacity probe plus machine-validated, release-bound supervised-pilot run, go/no-go and incident-exercise records.
|
||||||
- Backup, restore, opt-in systemd scheduling, deployment, persistence-drill, diagnostic, release-evidence, Google acceptance-record validation and rollback tooling.
|
- Native systemd API and worker deployment with persistent Data Protection keys, loopback-only HTTP, Nginx HTTPS, and version-selected rollback.
|
||||||
|
|
||||||
These capabilities still require their separately documented provider, host and operational acceptance. Google, PMS and payment-provider acceptance is not established by local automated tests.
|
These capabilities still require their separately documented provider, host and operational acceptance. Google, PMS and payment-provider acceptance is not established by local automated tests.
|
||||||
|
|
||||||
### Known limitations and launch conditions
|
### Known limitations and launch conditions
|
||||||
|
|
||||||
- Gate A still requires a successful default-branch CI run, durable off-host release archive, target-Debian deployment, persistent storage/key validation, monitoring, and a successful restore/rollback exercise.
|
- Gate A still requires a checksummed native package from the exact default-branch commit, Ansible installation on the target Debian host, persistent storage/key validation, monitoring, and a successful restore/rollback exercise.
|
||||||
- Gate B still requires real Google acceptance and supervised staff testing, including desktop-parity acceptance of pagination, draft protection, proxy-aware login throttling and saved-hotel-timezone rendering.
|
- Gate B still requires real Google acceptance and supervised staff testing, including desktop-parity acceptance of pagination, draft protection, proxy-aware login throttling and saved-hotel-timezone rendering.
|
||||||
- Gate C still requires the Rezlynx/Guestline adapter and independently accepted PMS/payment workflows, plus privacy, identity, capacity, and release approvals.
|
- Gate C still requires the Rezlynx/Guestline adapter and independently accepted PMS/payment workflows, plus privacy, identity, capacity, and release approvals.
|
||||||
- FAQ live mode and all external write actions must remain disabled until their corresponding acceptance gate has passed.
|
- FAQ live mode and all external write actions must remain disabled until their corresponding acceptance gate has passed.
|
||||||
|
|
||||||
See [MILESTONES.md](MILESTONES.md) for the gate assessment, delivery sequence, and remaining work.
|
See [MILESTONES.md](MILESTONES.md) for the gate assessment, delivery sequence, and remaining work.
|
||||||
|
|
||||||
|
## 0.2.0 — Superseded candidate identifier
|
||||||
|
|
||||||
|
The published `0.2.0` tag is retained unchanged for auditability but is not the approved deployment candidate. It identifies a development-line commit that is not on the clean Gate B release branch. Do not package or deploy it; `0.2.2` supersedes it.
|
||||||
|
|
||||||
## 0.1.0 — 29 September 2026
|
## 0.1.0 — 29 September 2026
|
||||||
|
|
||||||
The `0.1.0` tag identifies the initial GuestOps Web foundation. It is not approved for live hotel operations.
|
The `0.1.0` tag identifies the initial GuestOps Web foundation. It is not approved for live hotel operations.
|
||||||
@@ -36,9 +40,9 @@ The `0.1.0` tag identifies the initial GuestOps Web foundation. It is not approv
|
|||||||
- ASP.NET Core authentication with protected cookies, password hashing, CSRF validation, login throttling, role checks, and server-derived hotel membership.
|
- ASP.NET Core authentication with protected cookies, password hashing, CSRF validation, login throttling, role checks, and server-derived hotel membership.
|
||||||
- Tenant-scoped MongoDB storage with optimistic concurrency, unique mailbox/message indexes, OAuth state expiry, and worker leases.
|
- Tenant-scoped MongoDB storage with optimistic concurrency, unique mailbox/message indexes, OAuth state expiry, and worker leases.
|
||||||
- Read-only Google OAuth and recent-message import foundation with checkpoint and duplicate protection.
|
- Read-only Google OAuth and recent-message import foundation with checkpoint and duplicate protection.
|
||||||
- Preview mode, Linux container definitions, Nginx HTTPS example, and automated backend/frontend verification.
|
- Preview mode, native Linux packaging, Nginx HTTPS example, and automated backend/frontend verification.
|
||||||
- Live email sending, PMS writes, payment workflows, and automatic FAQ replies were disabled in this foundation.
|
- Live email sending, PMS writes, payment workflows, and automatic FAQ replies were disabled in this foundation.
|
||||||
|
|
||||||
### Versioning
|
### Versioning
|
||||||
|
|
||||||
The foundation remains tagged `0.1.0`. The .NET projects and frontend package now share candidate version `0.2.0`; create that immutable tag only after the exact commit, checksummed artifacts and Gate B acceptance evidence have been approved.
|
The foundation remains tagged `0.1.0`. The .NET projects and frontend package now share candidate version `0.2.2`; create that immutable tag only after the exact commit, checksummed artifacts and Gate B acceptance evidence have been approved.
|
||||||
|
|||||||
-77
@@ -1,77 +0,0 @@
|
|||||||
name: guestops
|
|
||||||
x-app-env: &app-env
|
|
||||||
Mongo__ConnectionString: mongodb://guestops:${MONGO_APP_PASSWORD:?Set MONGO_APP_PASSWORD}@mongo:27017/guestops?authSource=guestops
|
|
||||||
Mongo__Database: guestops
|
|
||||||
Keys__Path: /var/lib/guestops/keys
|
|
||||||
PublicUrl: https://sandbox-guestops.futuresens.co.uk
|
|
||||||
Google__ClientId: ${GOOGLE_CLIENT_ID:-}
|
|
||||||
Google__ClientSecret: ${GOOGLE_CLIENT_SECRET:-}
|
|
||||||
AutoReply__EnableLive: ${AUTO_REPLY_ENABLE_LIVE:-false}
|
|
||||||
Google__EnableSending: ${GOOGLE_ENABLE_SENDING:-false}
|
|
||||||
Logging__LogLevel__Default: Warning
|
|
||||||
Logging__LogLevel__Microsoft.AspNetCore.Hosting.Diagnostics: Warning
|
|
||||||
x-logging: &logging
|
|
||||||
driver: json-file
|
|
||||||
options: { max-size: "10m", max-file: "3" }
|
|
||||||
services:
|
|
||||||
api:
|
|
||||||
image: ${GUESTOPS_API_IMAGE:-guestops-api:local}
|
|
||||||
build: { context: ., target: api }
|
|
||||||
restart: unless-stopped
|
|
||||||
ports: ["127.0.0.1:8080:8080"]
|
|
||||||
environment:
|
|
||||||
<<: *app-env
|
|
||||||
ASPNETCORE_ENVIRONMENT: Production
|
|
||||||
AllowedHosts: sandbox-guestops.futuresens.co.uk;localhost;127.0.0.1
|
|
||||||
Proxy__KnownAddress: ${GUESTOPS_GATEWAY:-172.30.87.1}
|
|
||||||
Ai__ApiKey: ${AI_API_KEY:-}
|
|
||||||
Ai__Model: ${AI_MODEL:-}
|
|
||||||
Payments__ConfigFile: /run/guestops/payments.json
|
|
||||||
Pms__ConfigFile: /run/guestops/pms.json
|
|
||||||
volumes:
|
|
||||||
- app-keys:/var/lib/guestops/keys
|
|
||||||
- ${PMS_CONFIG_FILE_HOST:-./deploy/pms.example.json}:/run/guestops/pms.json:ro
|
|
||||||
- ${PAYMENTS_CONFIG_FILE_HOST:-./deploy/payments.example.json}:/run/guestops/payments.json:ro
|
|
||||||
depends_on:
|
|
||||||
mongo: { condition: service_healthy }
|
|
||||||
logging: *logging
|
|
||||||
mem_limit: 1g
|
|
||||||
security_opt: ["no-new-privileges:true"]
|
|
||||||
worker:
|
|
||||||
image: ${GUESTOPS_WORKER_IMAGE:-guestops-worker:local}
|
|
||||||
build: { context: ., target: worker }
|
|
||||||
restart: unless-stopped
|
|
||||||
environment: *app-env
|
|
||||||
volumes: ["app-keys:/var/lib/guestops/keys"]
|
|
||||||
depends_on:
|
|
||||||
mongo: { condition: service_healthy }
|
|
||||||
logging: *logging
|
|
||||||
mem_limit: 768m
|
|
||||||
security_opt: ["no-new-privileges:true"]
|
|
||||||
mongo:
|
|
||||||
image: mongo:8.0
|
|
||||||
restart: unless-stopped
|
|
||||||
environment:
|
|
||||||
MONGO_INITDB_ROOT_USERNAME: admin
|
|
||||||
MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD:?Set MONGO_ROOT_PASSWORD}
|
|
||||||
MONGO_APP_PASSWORD: ${MONGO_APP_PASSWORD:?Set MONGO_APP_PASSWORD}
|
|
||||||
volumes:
|
|
||||||
- mongo-data:/data/db
|
|
||||||
- ./deploy/mongo-init.js:/docker-entrypoint-initdb.d/guestops.js:ro
|
|
||||||
command: ["mongod", "--wiredTigerCacheSizeGB", "1"]
|
|
||||||
healthcheck:
|
|
||||||
test: ["CMD-SHELL", "mongosh --quiet --eval 'db.adminCommand({ping:1}).ok' | grep 1"]
|
|
||||||
interval: 10s
|
|
||||||
timeout: 5s
|
|
||||||
retries: 12
|
|
||||||
logging: *logging
|
|
||||||
mem_limit: 2500m
|
|
||||||
volumes:
|
|
||||||
mongo-data:
|
|
||||||
app-keys:
|
|
||||||
networks:
|
|
||||||
default:
|
|
||||||
ipam:
|
|
||||||
config:
|
|
||||||
- subnet: ${GUESTOPS_SUBNET:-172.30.87.0/24}
|
|
||||||
gateway: ${GUESTOPS_GATEWAY:-172.30.87.1}
|
|
||||||
@@ -1,128 +0,0 @@
|
|||||||
#!/usr/bin/env python3
|
|
||||||
"""Run a bounded, read-only capacity probe against an approved GuestOps sandbox."""
|
|
||||||
|
|
||||||
from __future__ import annotations
|
|
||||||
|
|
||||||
import argparse
|
|
||||||
import concurrent.futures
|
|
||||||
import datetime as dt
|
|
||||||
import http.cookiejar
|
|
||||||
import json
|
|
||||||
import os
|
|
||||||
from pathlib import Path
|
|
||||||
import re
|
|
||||||
import statistics
|
|
||||||
import time
|
|
||||||
import urllib.error
|
|
||||||
import urllib.parse
|
|
||||||
import urllib.request
|
|
||||||
|
|
||||||
|
|
||||||
PATHS = ("/health/ready", "/api/hotel", "/api/conversations/page")
|
|
||||||
|
|
||||||
|
|
||||||
def require(condition: bool, message: str) -> None:
|
|
||||||
if not condition:
|
|
||||||
raise ValueError(message)
|
|
||||||
|
|
||||||
|
|
||||||
def percentile(values: list[float], fraction: float) -> float:
|
|
||||||
ordered = sorted(values)
|
|
||||||
position = max(0, min(len(ordered) - 1, int(len(ordered) * fraction + 0.999999) - 1))
|
|
||||||
return ordered[position]
|
|
||||||
|
|
||||||
|
|
||||||
def summarize(results: list[tuple[bool, float]], concurrency: int) -> dict[str, object]:
|
|
||||||
require(len(results) > 0, "At least one probe result is required.")
|
|
||||||
latencies = [latency for _, latency in results]
|
|
||||||
successes = sum(1 for success, _ in results if success)
|
|
||||||
return {
|
|
||||||
"concurrency": concurrency,
|
|
||||||
"requests": len(results),
|
|
||||||
"successes": successes,
|
|
||||||
"failures": len(results) - successes,
|
|
||||||
"errorRate": round((len(results) - successes) / len(results), 6),
|
|
||||||
"latencyMs": {
|
|
||||||
"median": round(statistics.median(latencies), 2),
|
|
||||||
"p95": round(percentile(latencies, 0.95), 2),
|
|
||||||
"maximum": round(max(latencies), 2),
|
|
||||||
},
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
def login(origin: str, email: str, password: str) -> str:
|
|
||||||
jar = http.cookiejar.CookieJar()
|
|
||||||
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(jar))
|
|
||||||
with opener.open(origin + "/api/session", timeout=15) as response:
|
|
||||||
csrf = json.load(response)["csrfToken"]
|
|
||||||
body = json.dumps({"email": email, "password": password}).encode()
|
|
||||||
request = urllib.request.Request(origin + "/api/auth/login", data=body, method="POST", headers={"Content-Type": "application/json", "X-CSRF-TOKEN": csrf})
|
|
||||||
with opener.open(request, timeout=15) as response:
|
|
||||||
require(response.status == 200, "Sandbox login failed.")
|
|
||||||
cookies = "; ".join(f"{cookie.name}={cookie.value}" for cookie in jar)
|
|
||||||
require("guestops.session=" in cookies, "Sandbox did not issue a GuestOps session cookie.")
|
|
||||||
return cookies
|
|
||||||
|
|
||||||
|
|
||||||
def request_once(origin: str, cookie: str, number: int) -> tuple[bool, float]:
|
|
||||||
path = PATHS[number % len(PATHS)]
|
|
||||||
request = urllib.request.Request(origin + path, headers={"Cookie": cookie, "Accept": "application/json"})
|
|
||||||
started = time.perf_counter()
|
|
||||||
try:
|
|
||||||
with urllib.request.urlopen(request, timeout=20) as response:
|
|
||||||
success = response.status == 200
|
|
||||||
response.read(1024) # Bound local processing; never retain response or guest content.
|
|
||||||
except (OSError, urllib.error.HTTPError):
|
|
||||||
success = False
|
|
||||||
return success, (time.perf_counter() - started) * 1000
|
|
||||||
|
|
||||||
|
|
||||||
def main() -> None:
|
|
||||||
parser = argparse.ArgumentParser(description=__doc__)
|
|
||||||
parser.add_argument("--origin", required=True)
|
|
||||||
parser.add_argument("--requests", type=int, default=100)
|
|
||||||
parser.add_argument("--concurrency", type=int, default=5)
|
|
||||||
parser.add_argument("--release-commit", required=True)
|
|
||||||
parser.add_argument("--release-record-sha256", required=True)
|
|
||||||
parser.add_argument("--output", required=True, type=Path)
|
|
||||||
parser.add_argument("--confirm-sandbox", action="store_true")
|
|
||||||
args = parser.parse_args()
|
|
||||||
|
|
||||||
parsed = urllib.parse.urlparse(args.origin)
|
|
||||||
require(args.confirm_sandbox, "Use --confirm-sandbox after confirming the target and maintenance window.")
|
|
||||||
require(parsed.scheme == "https" and parsed.hostname and parsed.path in ("", "/") and not parsed.query and not parsed.fragment and not parsed.username,
|
|
||||||
"Origin must be an HTTPS origin without credentials, path, query or fragment.")
|
|
||||||
require(parsed.hostname != "localhost" and not parsed.hostname.startswith("127."), "Use the deployed HTTPS sandbox, not a development server.")
|
|
||||||
require(1 <= args.concurrency <= 20 and 1 <= args.requests <= 2000, "Probe bounds are 1–20 concurrent workers and 1–2000 requests.")
|
|
||||||
require(re.fullmatch(r"[0-9a-f]{40}", args.release_commit) is not None, "Use a full lowercase release commit SHA.")
|
|
||||||
require(re.fullmatch(r"[0-9a-f]{64}", args.release_record_sha256) is not None, "Use the release-record SHA-256.")
|
|
||||||
require(not args.output.exists() and args.output.parent.is_dir(), "Output must be a new file in an existing restricted directory.")
|
|
||||||
email = os.environ.get("CAPACITY_EMAIL", "")
|
|
||||||
password = os.environ.get("CAPACITY_PASSWORD", "")
|
|
||||||
require(email and password, "Set CAPACITY_EMAIL and CAPACITY_PASSWORD for a dedicated sandbox staff account.")
|
|
||||||
|
|
||||||
cookie = login(args.origin.rstrip("/"), email, password)
|
|
||||||
with concurrent.futures.ThreadPoolExecutor(max_workers=args.concurrency) as pool:
|
|
||||||
results = list(pool.map(lambda number: request_once(args.origin.rstrip("/"), cookie, number), range(args.requests)))
|
|
||||||
report = {
|
|
||||||
"schemaVersion": 1,
|
|
||||||
"kind": "guestops-read-only-capacity",
|
|
||||||
"recordedAt": dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z"),
|
|
||||||
"originHost": parsed.hostname,
|
|
||||||
"releaseCommit": args.release_commit,
|
|
||||||
"releaseRecordSha256": args.release_record_sha256,
|
|
||||||
"paths": list(PATHS),
|
|
||||||
**summarize(results, args.concurrency),
|
|
||||||
}
|
|
||||||
descriptor = os.open(args.output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
|
|
||||||
with os.fdopen(descriptor, "w", encoding="utf-8") as output:
|
|
||||||
output.write(json.dumps(report, indent=2, sort_keys=True) + "\n")
|
|
||||||
print(f"Capacity probe completed: {report['successes']}/{report['requests']} successful; p95 {report['latencyMs']['p95']} ms. Review against the approved target before release.")
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
try:
|
|
||||||
main()
|
|
||||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
|
||||||
print(f"Capacity probe stopped: {error}", file=__import__("sys").stderr)
|
|
||||||
raise SystemExit(1)
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
const guestops = db.getSiblingDB('guestops');
|
|
||||||
guestops.createUser({user: 'guestops', pwd: process.env.MONGO_APP_PASSWORD, roles: [{role: 'readWrite', db: 'guestops'}]});
|
|
||||||
@@ -1,31 +0,0 @@
|
|||||||
# Install within the existing Nginx configuration. Obtain the certificate first.
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
server_name sandbox-guestops.futuresens.co.uk;
|
|
||||||
location /.well-known/acme-challenge/ { root /var/www/letsencrypt; }
|
|
||||||
location / { return 301 https://$host$request_uri; }
|
|
||||||
}
|
|
||||||
server {
|
|
||||||
listen 443 ssl;
|
|
||||||
server_name sandbox-guestops.futuresens.co.uk;
|
|
||||||
ssl_certificate /etc/letsencrypt/live/sandbox-guestops.futuresens.co.uk/fullchain.pem;
|
|
||||||
ssl_certificate_key /etc/letsencrypt/live/sandbox-guestops.futuresens.co.uk/privkey.pem;
|
|
||||||
ssl_protocols TLSv1.2 TLSv1.3;
|
|
||||||
add_header Strict-Transport-Security "max-age=31536000" always;
|
|
||||||
client_max_body_size 128k;
|
|
||||||
# OAuth authorization codes and state must not appear in access logs.
|
|
||||||
location = /api/integrations/google/callback {
|
|
||||||
access_log off;
|
|
||||||
proxy_pass http://127.0.0.1:8080;
|
|
||||||
proxy_set_header Host $host;
|
|
||||||
proxy_set_header X-Forwarded-Proto https;
|
|
||||||
}
|
|
||||||
location / {
|
|
||||||
proxy_pass http://127.0.0.1:8080;
|
|
||||||
proxy_http_version 1.1;
|
|
||||||
proxy_set_header Host $host;
|
|
||||||
proxy_set_header X-Forwarded-Proto https;
|
|
||||||
proxy_set_header X-Forwarded-For $remote_addr;
|
|
||||||
proxy_read_timeout 60s;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
-344
@@ -1,344 +0,0 @@
|
|||||||
#!/usr/bin/env python3
|
|
||||||
"""GuestOps dedicated-Compose operations. Never prints credentials or provider data."""
|
|
||||||
import argparse
|
|
||||||
import contextlib
|
|
||||||
import hashlib
|
|
||||||
import json
|
|
||||||
import os
|
|
||||||
from pathlib import Path
|
|
||||||
import re
|
|
||||||
import shutil
|
|
||||||
import stat
|
|
||||||
import subprocess
|
|
||||||
import sys
|
|
||||||
import tarfile
|
|
||||||
import tempfile
|
|
||||||
import time
|
|
||||||
import urllib.request
|
|
||||||
import uuid
|
|
||||||
|
|
||||||
ROOT = Path(__file__).resolve().parents[1]
|
|
||||||
FILES = {"mongo.archive.gz", "keys.tar.gz", "configuration.json", "manifest.json"}
|
|
||||||
LIMIT = 8 * 1024**3
|
|
||||||
|
|
||||||
|
|
||||||
def require(condition, message):
|
|
||||||
if not condition:
|
|
||||||
raise RuntimeError(message)
|
|
||||||
|
|
||||||
|
|
||||||
def run(args, *, output=None, input_file=None, timeout=900):
|
|
||||||
# Provider output may contain secrets; errors identify only the program.
|
|
||||||
result = subprocess.run(args, cwd=ROOT, stdin=input_file or subprocess.DEVNULL,
|
|
||||||
stdout=output or subprocess.PIPE, stderr=subprocess.PIPE, timeout=timeout)
|
|
||||||
require(result.returncode == 0, f"{args[0]} step failed. Check the private operator environment; no command output was logged.")
|
|
||||||
return result.stdout or b""
|
|
||||||
|
|
||||||
|
|
||||||
def compose(*args, **kwargs):
|
|
||||||
return run(["docker", "compose", *args], **kwargs)
|
|
||||||
|
|
||||||
|
|
||||||
def digest(path):
|
|
||||||
with path.open("rb") as stream:
|
|
||||||
return hashlib.file_digest(stream, "sha256").hexdigest()
|
|
||||||
|
|
||||||
|
|
||||||
def image_id(image):
|
|
||||||
require(not image.startswith("-"), "Invalid image reference.")
|
|
||||||
return run(["docker", "image", "inspect", "--format", "{{.Id}}", image]).decode().strip()
|
|
||||||
|
|
||||||
|
|
||||||
def provider_configured(config, target):
|
|
||||||
section = "Pms" if target == "/run/guestops/pms.json" else "Payments"
|
|
||||||
# Only the exact shipped empty template is public; unknown settings fail closed.
|
|
||||||
return config not in ({}, {section: {"Hotels": {}}})
|
|
||||||
|
|
||||||
|
|
||||||
def persistence_layout(config):
|
|
||||||
"""Return the resolved named volumes required to survive recreation."""
|
|
||||||
services = config["services"]
|
|
||||||
declared = config.get("volumes", {})
|
|
||||||
|
|
||||||
def volume_for(service, target):
|
|
||||||
matches = [v for v in services[service].get("volumes", []) if v["target"] == target]
|
|
||||||
require(len(matches) == 1 and matches[0]["type"] == "volume" and matches[0].get("source"),
|
|
||||||
f"{service} requires one named persistent volume at {target}.")
|
|
||||||
source = matches[0]["source"]
|
|
||||||
require(source in declared, f"{service} volume {source} must be declared at the top level.")
|
|
||||||
return declared[source].get("name") or source
|
|
||||||
|
|
||||||
api_keys = volume_for("api", "/var/lib/guestops/keys")
|
|
||||||
worker_keys = volume_for("worker", "/var/lib/guestops/keys")
|
|
||||||
require(api_keys == worker_keys, "API and worker key volumes differ.")
|
|
||||||
mongo_data = volume_for("mongo", "/data/db")
|
|
||||||
require(api_keys != mongo_data, "Database and key data require separate named volumes.")
|
|
||||||
return {"keys": api_keys, "database": mongo_data}
|
|
||||||
|
|
||||||
|
|
||||||
AUTH = 'const c=new Mongo("mongodb://127.0.0.1"); c.getDB("admin").auth(process.env.MONGO_INITDB_ROOT_USERNAME,process.env.MONGO_INITDB_ROOT_PASSWORD);'
|
|
||||||
INVENTORY = 'const d=c.getDB("guestops"); print(JSON.stringify({bytes:d.stats().storageSize+d.stats().indexSize,collections:Object.fromEntries(d.getCollectionNames().filter(n=>!n.startsWith("system.")).sort().map(n=>[n,{count:d.getCollection(n).countDocuments({}),indexes:d.getCollection(n).getIndexes().map(i=>{delete i.ns;return i;}).sort((a,b)=>a.name.localeCompare(b.name))}]))}));'
|
|
||||||
|
|
||||||
|
|
||||||
def mongo(script):
|
|
||||||
return compose("exec", "-T", "mongo", "mongosh", "--quiet", "--nodb", "--eval", AUTH + script)
|
|
||||||
|
|
||||||
|
|
||||||
def configuration():
|
|
||||||
config = json.loads(compose("config", "--format", "json"))
|
|
||||||
services = config["services"]
|
|
||||||
require(set(services) == {"api", "worker", "mongo"}, "This tool supports the dedicated three-service GuestOps Compose deployment only.")
|
|
||||||
require(not services["mongo"].get("ports"), "MongoDB must not have published ports.")
|
|
||||||
ports = services["api"].get("ports", [])
|
|
||||||
require(len(ports) == 1 and ports[0].get("host_ip") == "127.0.0.1" and int(ports[0]["target"]) == 8080, "API must publish only port 8080 on loopback.")
|
|
||||||
require(not services["worker"].get("ports"), "Worker must not publish ports.")
|
|
||||||
for name in ("api", "worker"):
|
|
||||||
env = services[name]["environment"]
|
|
||||||
require(env.get("Mongo__Database") == "guestops" and "@mongo:27017/guestops?" in env.get("Mongo__ConnectionString", ""), "Backup supports only the dedicated Compose guestops database.")
|
|
||||||
require(str(env.get("Preview", "false")).lower() != "true", "Production preview is forbidden.")
|
|
||||||
require(env.get("Keys__Path") == "/var/lib/guestops/keys", "Unexpected key directory.")
|
|
||||||
require(services["api"]["environment"].get("ASPNETCORE_ENVIRONMENT") == "Production", "API must use Production environment.")
|
|
||||||
require(re.fullmatch(r"https://[A-Za-z0-9.-]+", services["api"]["environment"].get("PublicUrl", "")), "PublicUrl must be an HTTPS hostname without a path.")
|
|
||||||
persistence_layout(config)
|
|
||||||
return config
|
|
||||||
|
|
||||||
|
|
||||||
def wait_for(action, message, attempts=60):
|
|
||||||
for attempt in range(attempts):
|
|
||||||
try:
|
|
||||||
action()
|
|
||||||
return
|
|
||||||
except Exception:
|
|
||||||
if attempt == attempts - 1:
|
|
||||||
raise RuntimeError(message)
|
|
||||||
time.sleep(1)
|
|
||||||
|
|
||||||
|
|
||||||
def volume_identity(name):
|
|
||||||
require(not name.startswith("-"), "Invalid volume name.")
|
|
||||||
details = json.loads(run(["docker", "volume", "inspect", name]))
|
|
||||||
require(len(details) == 1 and details[0].get("Name") == name, "Named volume inspection failed.")
|
|
||||||
return {"name": name, "driver": details[0].get("Driver"), "scope": details[0].get("Scope")}
|
|
||||||
|
|
||||||
|
|
||||||
def readiness():
|
|
||||||
with urllib.request.urlopen("http://127.0.0.1:8080/health/ready", timeout=10) as response:
|
|
||||||
require(json.load(response) == {"status": "ready"}, "Loopback readiness failed.")
|
|
||||||
|
|
||||||
|
|
||||||
def persistence_drill(args):
|
|
||||||
require(args.confirm_restart, "Persistence drill requires --confirm-restart: all services will be restarted and application containers recreated.")
|
|
||||||
config = configuration()
|
|
||||||
layout = persistence_layout(config)
|
|
||||||
before_volumes = {purpose: volume_identity(name) for purpose, name in layout.items()}
|
|
||||||
before_inventory = json.loads(mongo(INVENTORY))
|
|
||||||
probe = compose("run", "--rm", "--no-deps", "-T", "-e", "Logging__LogLevel__Default=None", "api", "--backup-probe").decode().strip()
|
|
||||||
require(re.fullmatch(r"[A-Za-z0-9_-]{20,4096}", probe), "Key probe did not return a valid protected value.")
|
|
||||||
|
|
||||||
# Restart the database first, then its clients, so recovery is exercised in a known order.
|
|
||||||
compose("restart", "-t", "150", "mongo")
|
|
||||||
wait_for(lambda: mongo('const r=c.getDB("admin").runCommand({ping:1});if(!r.ok)quit(1);'), "MongoDB did not recover after restart.")
|
|
||||||
compose("restart", "-t", "150", "api", "worker")
|
|
||||||
wait_for(readiness, "API readiness did not recover after restart.")
|
|
||||||
|
|
||||||
# Recreate stateless containers as an image upgrade would, without rebuilding or changing data volumes.
|
|
||||||
compose("up", "-d", "--no-build", "--force-recreate", "api", "worker")
|
|
||||||
wait_for(readiness, "API readiness did not recover after container recreation.")
|
|
||||||
compose("run", "--rm", "--no-deps", "-T", "-e", "Logging__LogLevel__Default=None", "-e", "BACKUP_PROBE=" + probe, "api", "--verify-backup-probe")
|
|
||||||
|
|
||||||
after_volumes = {purpose: volume_identity(name) for purpose, name in layout.items()}
|
|
||||||
after_inventory = json.loads(mongo(INVENTORY))
|
|
||||||
require(after_volumes == before_volumes, "A persistent volume identity changed during the drill.")
|
|
||||||
require(after_inventory["collections"] == before_inventory["collections"], "Database collection counts or indexes changed during the drill.")
|
|
||||||
print("Persistence drill passed: named volumes, database counts/indexes, data-protection keys and readiness survived restart and container recreation.")
|
|
||||||
|
|
||||||
|
|
||||||
def preflight(args):
|
|
||||||
config = configuration()
|
|
||||||
env_file = ROOT / ".env"
|
|
||||||
require(env_file.is_file() and not env_file.is_symlink(), "Create a private .env file before deployment.")
|
|
||||||
require(stat.S_IMODE(env_file.stat().st_mode) & 0o077 == 0, ".env must not be accessible to group or other users.")
|
|
||||||
require(shutil.disk_usage(ROOT).free >= 8 * 1024**3, "Keep at least 8 GiB free before deployment; allow extra room for backups.")
|
|
||||||
for name, service in config["services"].items():
|
|
||||||
image_id(service["image"])
|
|
||||||
for volume in service.get("volumes", []):
|
|
||||||
if volume["type"] == "bind":
|
|
||||||
require(Path(volume["source"]).exists(), f"A required {name} bind mount is missing.")
|
|
||||||
if volume["target"] in ("/run/guestops/pms.json", "/run/guestops/payments.json"):
|
|
||||||
provider = Path(volume["source"])
|
|
||||||
if provider_configured(json.loads(provider.read_text()), volume["target"]):
|
|
||||||
require(stat.S_IMODE(provider.stat().st_mode) & 0o077 == 0, "Configured provider files must not be accessible to group or other users.")
|
|
||||||
if not args.offline:
|
|
||||||
url = config["services"]["api"]["environment"]["PublicUrl"]
|
|
||||||
require(re.fullmatch(r"https://[A-Za-z0-9.-]+", url), "PublicUrl must be an HTTPS hostname without a path.")
|
|
||||||
with urllib.request.urlopen(url + "/health/ready", timeout=15) as response:
|
|
||||||
require(response.url == url + "/health/ready" and json.load(response) == {"status": "ready"}, "Public HTTPS readiness failed.")
|
|
||||||
print("Preflight passed: private database, loopback API, production settings, images, mounts and disk headroom" + ("; HTTPS not checked." if args.offline else "; public HTTPS and database readiness checked."))
|
|
||||||
|
|
||||||
|
|
||||||
@contextlib.contextmanager
|
|
||||||
def maintenance_lock():
|
|
||||||
import fcntl
|
|
||||||
with (ROOT / ".guestops-maintenance.lock").open("a") as lock:
|
|
||||||
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
||||||
yield
|
|
||||||
|
|
||||||
|
|
||||||
def backup(args):
|
|
||||||
require(args.confirm_maintenance, "Backup requires --confirm-maintenance: API and workers will briefly stop.")
|
|
||||||
require(re.fullmatch(r"[A-Fa-f0-9]{40}", args.recipient), "Use a verified full 40-character GPG recipient fingerprint.")
|
|
||||||
run(["gpg", "--batch", "--list-keys", args.recipient])
|
|
||||||
destination = Path(args.output).resolve()
|
|
||||||
require(not destination.exists(), "Backup output already exists; choose a new filename.")
|
|
||||||
require(destination.parent.is_dir(), "Create the private backup directory first.")
|
|
||||||
require(stat.S_IMODE(destination.parent.stat().st_mode) & 0o077 == 0, "Backup directory must be private (mode 700).")
|
|
||||||
config = configuration()
|
|
||||||
runtime = {}
|
|
||||||
for service in ("api", "worker", "mongo"):
|
|
||||||
cid = compose("ps", "--status", "running", "-q", service).decode().strip()
|
|
||||||
require(re.fullmatch(r"[a-f0-9]{12,64}", cid), f"Exactly one running {service} container is required.")
|
|
||||||
runtime[service] = json.loads(run(["docker", "inspect", cid]))[0]
|
|
||||||
require(shutil.disk_usage(destination.parent).free >= 3 * json.loads(mongo(INVENTORY))["bytes"] + 1024**3, "Insufficient free space for a consistent encrypted backup.")
|
|
||||||
partial = destination.with_name(destination.name + ".partial-" + uuid.uuid4().hex)
|
|
||||||
with maintenance_lock(), tempfile.TemporaryDirectory(prefix="guestops-backup-", dir=destination.parent) as folder:
|
|
||||||
folder = Path(folder)
|
|
||||||
stopped = False
|
|
||||||
ttl = None
|
|
||||||
try:
|
|
||||||
# Set before stopping so partial stop failures also attempt recovery.
|
|
||||||
stopped = True
|
|
||||||
compose("stop", "-t", "150", "api", "worker")
|
|
||||||
ttl = json.loads(mongo('print(JSON.stringify(c.getDB("admin").runCommand({getParameter:1,ttlMonitorEnabled:1}).ttlMonitorEnabled));'))
|
|
||||||
require(isinstance(ttl, bool), "Cannot determine MongoDB TTL monitor state.")
|
|
||||||
mongo('const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:false});if(!r.ok)quit(1);')
|
|
||||||
inventory = json.loads(mongo(INVENTORY))
|
|
||||||
dump = 'set -eu; case "$MONGO_INITDB_ROOT_PASSWORD" in ""|*[!0-9a-fA-F]*) exit 1;; esac; umask 077; cfg=$(mktemp); trap \'rm -f "$cfg"\' EXIT; printf \'password: "%s"\\n\' "$MONGO_INITDB_ROOT_PASSWORD" > "$cfg"; mongodump --config "$cfg" --username "$MONGO_INITDB_ROOT_USERNAME" --authenticationDatabase admin --db guestops --archive --gzip'
|
|
||||||
with (folder / "mongo.archive.gz").open("wb") as output:
|
|
||||||
compose("exec", "-T", "mongo", "sh", "-c", dump, output=output)
|
|
||||||
probe = compose("run", "--rm", "--no-deps", "-T", "-e", "Logging__LogLevel__Default=None", "api", "--backup-probe").decode().strip()
|
|
||||||
require(re.fullmatch(r"[A-Za-z0-9_-]{20,4096}", probe), "Key probe did not return a valid protected value.")
|
|
||||||
with (folder / "keys.tar.gz").open("wb") as output:
|
|
||||||
compose("run", "--rm", "--no-deps", "-T", "--entrypoint", "tar", "api", "-C", "/var/lib/guestops/keys", "-czf", "-", ".", output=output)
|
|
||||||
mounted = {}
|
|
||||||
for volume in config["services"]["api"].get("volumes", []):
|
|
||||||
if volume["type"] == "bind" and volume["target"] in ("/run/guestops/pms.json", "/run/guestops/payments.json"):
|
|
||||||
mounted[volume["target"]] = Path(volume["source"]).read_text()
|
|
||||||
(folder / "configuration.json").write_text(json.dumps({"compose": config, "runtime": runtime, "providerFiles": mounted}))
|
|
||||||
manifest = {"format": 1, "createdAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "inventory": inventory, "probe": probe, "apiImageId": runtime["api"]["Image"], "mongoImageId": runtime["mongo"]["Image"], "sha256": {name: digest(folder / name) for name in FILES - {"manifest.json"}}}
|
|
||||||
(folder / "manifest.json").write_text(json.dumps(manifest))
|
|
||||||
finally:
|
|
||||||
try:
|
|
||||||
if ttl is not None:
|
|
||||||
mongo('const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:' + str(ttl).lower() + '});if(!r.ok)quit(1);')
|
|
||||||
finally:
|
|
||||||
if stopped:
|
|
||||||
compose("start", "api", "worker")
|
|
||||||
try:
|
|
||||||
with tarfile.open(folder / "bundle.tar", "w") as archive:
|
|
||||||
for name in sorted(FILES):
|
|
||||||
archive.add(folder / name, arcname=name, recursive=False)
|
|
||||||
run(["gpg", "--batch", "--trust-model", "always", "--recipient", args.recipient, "--output", str(partial), "--encrypt", str(folder / "bundle.tar")])
|
|
||||||
os.link(partial, destination) # Atomic publication, never overwrite an existing backup.
|
|
||||||
finally:
|
|
||||||
partial.unlink(missing_ok=True)
|
|
||||||
print("Encrypted backup complete. Copy it off-server and perform a restore drill.")
|
|
||||||
|
|
||||||
|
|
||||||
def scheduled_backup(args):
|
|
||||||
require(args.confirm_maintenance, "Scheduled backup requires --confirm-maintenance because API and workers will briefly stop.")
|
|
||||||
recipient = os.environ.get("BACKUP_RECIPIENT", "")
|
|
||||||
directory_value = os.environ.get("BACKUP_DIRECTORY", "")
|
|
||||||
require(re.fullmatch(r"[A-Fa-f0-9]{40}", recipient), "BACKUP_RECIPIENT must be a verified full GPG fingerprint.")
|
|
||||||
require(directory_value != "", "BACKUP_DIRECTORY must name the private off-checkout staging directory.")
|
|
||||||
requested_directory = Path(directory_value)
|
|
||||||
require(requested_directory.is_absolute() and not requested_directory.is_symlink(), "BACKUP_DIRECTORY must be an absolute, non-symlink path.")
|
|
||||||
directory = requested_directory.resolve()
|
|
||||||
require(directory.is_dir(), "BACKUP_DIRECTORY must be an existing real directory.")
|
|
||||||
require(ROOT not in directory.parents and directory != ROOT, "Scheduled backups must be staged outside the application checkout.")
|
|
||||||
require(stat.S_IMODE(directory.stat().st_mode) & 0o077 == 0, "BACKUP_DIRECTORY must be private (mode 700).")
|
|
||||||
timestamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
|
|
||||||
destination = directory / f"guestops-{timestamp}.tar.gpg"
|
|
||||||
backup(argparse.Namespace(confirm_maintenance=True, recipient=recipient, output=str(destination)))
|
|
||||||
print(f"Scheduled backup staged as {destination.name}. Off-host transfer and alert verification remain required.")
|
|
||||||
|
|
||||||
|
|
||||||
def unpack(bundle, folder):
|
|
||||||
with tarfile.open(bundle, "r:") as archive:
|
|
||||||
members = archive.getmembers()
|
|
||||||
require(len(members) == len(FILES) and {m.name for m in members} == FILES, "Unexpected backup members.")
|
|
||||||
require(all(m.isfile() and 0 <= m.size <= LIMIT for m in members) and sum(m.size for m in members) <= LIMIT, "Invalid or oversized backup members.")
|
|
||||||
for member in members:
|
|
||||||
with archive.extractfile(member) as source, (folder / member.name).open("xb") as output:
|
|
||||||
shutil.copyfileobj(source, output)
|
|
||||||
manifest = json.loads((folder / "manifest.json").read_text())
|
|
||||||
require(manifest.get("format") == 1 and set(manifest.get("sha256", {})) == FILES - {"manifest.json"}, "Unsupported backup format.")
|
|
||||||
for name, expected in manifest["sha256"].items():
|
|
||||||
require(digest(folder / name) == expected, "Backup checksum verification failed.")
|
|
||||||
return manifest
|
|
||||||
|
|
||||||
|
|
||||||
def restore_drill(args):
|
|
||||||
backup_file = Path(args.backup).resolve()
|
|
||||||
require(backup_file.is_file(), "Backup file is missing.")
|
|
||||||
with tempfile.TemporaryDirectory(prefix="guestops-restore-", dir=ROOT) as temp:
|
|
||||||
folder = Path(temp)
|
|
||||||
run(["gpg", "--batch", "--max-output", str(LIMIT), "--output", str(folder / "bundle.tar"), "--decrypt", str(backup_file)])
|
|
||||||
require((folder / "bundle.tar").stat().st_size <= LIMIT, "Decrypted bundle exceeds the 8 GiB pilot limit.")
|
|
||||||
manifest = unpack(folder / "bundle.tar", folder)
|
|
||||||
require(image_id(args.api_image) == manifest["apiImageId"] and image_id(args.mongo_image) == manifest["mongoImageId"], "Load the exact trusted API and MongoDB images used for this backup.")
|
|
||||||
require(shutil.disk_usage(ROOT).free > 3 * manifest["inventory"]["bytes"] + 1024**3, "Insufficient restore drill space.")
|
|
||||||
keys = folder / "keys"
|
|
||||||
keys.mkdir(mode=0o700)
|
|
||||||
with tarfile.open(folder / "keys.tar.gz", "r:gz") as archive:
|
|
||||||
total = 0
|
|
||||||
for member in archive:
|
|
||||||
if member.name in (".", "./") and member.isdir():
|
|
||||||
continue
|
|
||||||
name = member.name.removeprefix("./")
|
|
||||||
total += member.size
|
|
||||||
require(member.isfile() and re.fullmatch(r"[A-Za-z0-9_-]+\.xml", name) and member.size < 1024**2 and total < 16 * 1024**2, "Invalid key archive.")
|
|
||||||
with archive.extractfile(member) as source, (keys / name).open("xb") as output:
|
|
||||||
shutil.copyfileobj(source, output)
|
|
||||||
run(["docker", "run", "--rm", "--pull", "never", "--network", "none", "--user", "0:0", "--read-only", "--mount", f"type=bind,src={keys},dst=/var/lib/guestops/keys,readonly", "-e", "Logging__LogLevel__Default=None", "-e", "BACKUP_PROBE=" + manifest["probe"], args.api_image, "--verify-backup-probe"])
|
|
||||||
cid = run(["docker", "run", "-d", "--pull", "never", "--network", "none", "--memory", "1g", "--label", "guestops.restore-drill=true", args.mongo_image, "--bind_ip", "127.0.0.1", "--setParameter", "ttlMonitorEnabled=false"]).decode().strip()
|
|
||||||
require(re.fullmatch(r"[a-f0-9]{64}", cid), "Unexpected restore container identifier.")
|
|
||||||
try:
|
|
||||||
for attempt in range(30):
|
|
||||||
try:
|
|
||||||
run(["docker", "exec", cid, "mongosh", "--quiet", "--eval", "db.adminCommand({ping:1})"], timeout=10)
|
|
||||||
break
|
|
||||||
except RuntimeError:
|
|
||||||
if attempt == 29:
|
|
||||||
raise
|
|
||||||
time.sleep(1)
|
|
||||||
with (folder / "mongo.archive.gz").open("rb") as source:
|
|
||||||
run(["docker", "exec", "-i", cid, "mongorestore", "--archive", "--gzip", "--nsInclude", "guestops.*"], input_file=source)
|
|
||||||
restored = json.loads(run(["docker", "exec", cid, "mongosh", "--quiet", "--nodb", "--eval", 'const c=new Mongo("mongodb://127.0.0.1");' + INVENTORY]))
|
|
||||||
require(restored["collections"] == manifest["inventory"]["collections"], "Restored collection counts or indexes differ.")
|
|
||||||
finally:
|
|
||||||
run(["docker", "rm", "-f", "-v", cid]) # Only the exact container created above and its anonymous volumes.
|
|
||||||
print("Restore drill passed: collection counts, indexes and actual key decryption verified in isolated containers. Production was not restored or modified.")
|
|
||||||
|
|
||||||
|
|
||||||
def main():
|
|
||||||
require(os.name == "posix", "Run deployment operations on Linux.")
|
|
||||||
os.umask(0o077)
|
|
||||||
parser = argparse.ArgumentParser(description=__doc__)
|
|
||||||
subs = parser.add_subparsers(dest="command", required=True)
|
|
||||||
check = subs.add_parser("preflight"); check.add_argument("--offline", action="store_true")
|
|
||||||
persistence = subs.add_parser("persistence-drill"); persistence.add_argument("--confirm-restart", action="store_true")
|
|
||||||
save = subs.add_parser("backup"); save.add_argument("--recipient", required=True); save.add_argument("--output", required=True); save.add_argument("--confirm-maintenance", action="store_true")
|
|
||||||
scheduled = subs.add_parser("scheduled-backup"); scheduled.add_argument("--confirm-maintenance", action="store_true")
|
|
||||||
drill = subs.add_parser("restore-drill"); drill.add_argument("backup"); drill.add_argument("--api-image", required=True); drill.add_argument("--mongo-image", default="mongo:8.0")
|
|
||||||
args = parser.parse_args()
|
|
||||||
{"preflight": preflight, "persistence-drill": persistence_drill, "backup": backup, "scheduled-backup": scheduled_backup, "restore-drill": restore_drill}[args.command](args)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
try:
|
|
||||||
main()
|
|
||||||
except Exception as error:
|
|
||||||
# Never include subprocess output, config values or parsed guest data.
|
|
||||||
print(str(error) if isinstance(error, RuntimeError) else "Operation failed (" + type(error).__name__ + "). No sensitive details were logged.", file=sys.stderr)
|
|
||||||
sys.exit(1)
|
|
||||||
|
|
||||||
@@ -0,0 +1,207 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Build a deterministic self-contained Linux GuestOps release archive."""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import gzip
|
||||||
|
import io
|
||||||
|
import json
|
||||||
|
from pathlib import Path
|
||||||
|
import re
|
||||||
|
import shutil
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
import tarfile
|
||||||
|
import tempfile
|
||||||
|
import xml.etree.ElementTree as ET
|
||||||
|
from collections.abc import Callable, Sequence
|
||||||
|
|
||||||
|
|
||||||
|
SEMVER = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+")
|
||||||
|
FULL_SHA = re.compile(r"[0-9a-f]{40}")
|
||||||
|
LINUX_RUNTIME = "linux-x64"
|
||||||
|
Runner = Callable[[Sequence[str], Path], None]
|
||||||
|
|
||||||
|
|
||||||
|
def git(repository: Path, *arguments: str, binary: bool = False) -> bytes | str:
|
||||||
|
result = subprocess.run(
|
||||||
|
["git", "-C", str(repository), *arguments],
|
||||||
|
check=True,
|
||||||
|
capture_output=True,
|
||||||
|
text=not binary,
|
||||||
|
)
|
||||||
|
return result.stdout if binary else result.stdout.strip()
|
||||||
|
|
||||||
|
|
||||||
|
def committed_text(repository: Path, commit: str, path: str) -> str:
|
||||||
|
return str(git(repository, "show", f"{commit}:{path}"))
|
||||||
|
|
||||||
|
|
||||||
|
def versions(repository: Path, commit: str) -> tuple[str, str]:
|
||||||
|
props = ET.fromstring(committed_text(repository, commit, "Directory.Build.props"))
|
||||||
|
version_node = props.find(".//Version")
|
||||||
|
if version_node is None or not version_node.text:
|
||||||
|
raise ValueError("The committed Directory.Build.props has no Version element.")
|
||||||
|
dotnet_version = version_node.text.strip()
|
||||||
|
package = json.loads(committed_text(repository, commit, "web/package.json"))
|
||||||
|
return dotnet_version, str(package.get("version", ""))
|
||||||
|
|
||||||
|
|
||||||
|
def run_build(arguments: Sequence[str], working_directory: Path) -> None:
|
||||||
|
command = list(arguments)
|
||||||
|
executable = shutil.which(command[0])
|
||||||
|
if executable is None:
|
||||||
|
raise FileNotFoundError(f"Required build tool is not installed: {command[0]}")
|
||||||
|
command[0] = executable
|
||||||
|
subprocess.run(command, cwd=working_directory, check=True)
|
||||||
|
|
||||||
|
|
||||||
|
def extract_commit(repository: Path, commit: str, destination: Path) -> None:
|
||||||
|
archive = bytes(git(repository, "archive", "--format=tar", commit, binary=True))
|
||||||
|
with tarfile.open(fileobj=io.BytesIO(archive), mode="r:") as source:
|
||||||
|
source.extractall(destination, filter="data")
|
||||||
|
|
||||||
|
|
||||||
|
def add_directory(package: tarfile.TarFile, name: str) -> None:
|
||||||
|
entry = tarfile.TarInfo(name.rstrip("/") + "/")
|
||||||
|
entry.type = tarfile.DIRTYPE
|
||||||
|
entry.mode = 0o755
|
||||||
|
entry.uid = entry.gid = 0
|
||||||
|
entry.uname = entry.gname = "root"
|
||||||
|
entry.mtime = 0
|
||||||
|
package.addfile(entry)
|
||||||
|
|
||||||
|
|
||||||
|
def add_file(package: tarfile.TarFile, source: Path, name: str, executable: bool) -> None:
|
||||||
|
content = source.read_bytes()
|
||||||
|
entry = tarfile.TarInfo(name)
|
||||||
|
entry.size = len(content)
|
||||||
|
entry.mode = 0o755 if executable else 0o644
|
||||||
|
entry.uid = entry.gid = 0
|
||||||
|
entry.uname = entry.gname = "root"
|
||||||
|
entry.mtime = 0
|
||||||
|
package.addfile(entry, io.BytesIO(content))
|
||||||
|
|
||||||
|
|
||||||
|
def release_bytes(release: Path, version: str) -> bytes:
|
||||||
|
prefix = f"guestops_{version}"
|
||||||
|
tar_bytes = io.BytesIO()
|
||||||
|
with tarfile.open(fileobj=tar_bytes, mode="w", format=tarfile.PAX_FORMAT) as package:
|
||||||
|
add_directory(package, prefix)
|
||||||
|
for component in ("api", "worker"):
|
||||||
|
root = release / component
|
||||||
|
add_directory(package, f"{prefix}/{component}")
|
||||||
|
for path in sorted(root.rglob("*"), key=lambda item: item.as_posix()):
|
||||||
|
relative = path.relative_to(release).as_posix()
|
||||||
|
target = f"{prefix}/{relative}"
|
||||||
|
if path.is_dir():
|
||||||
|
add_directory(package, target)
|
||||||
|
elif path.is_file():
|
||||||
|
add_file(
|
||||||
|
package,
|
||||||
|
path,
|
||||||
|
target,
|
||||||
|
relative in {"api/GuestOps.Api", "worker/GuestOps.Worker"},
|
||||||
|
)
|
||||||
|
compressed = io.BytesIO()
|
||||||
|
with gzip.GzipFile(fileobj=compressed, mode="wb", filename="", mtime=0) as stream:
|
||||||
|
stream.write(tar_bytes.getvalue())
|
||||||
|
return compressed.getvalue()
|
||||||
|
|
||||||
|
|
||||||
|
def build_package(
|
||||||
|
repository: Path,
|
||||||
|
ref: str,
|
||||||
|
output_directory: Path,
|
||||||
|
runner: Runner = run_build,
|
||||||
|
) -> tuple[Path, dict[str, str]]:
|
||||||
|
repository = repository.resolve()
|
||||||
|
output_directory = output_directory.resolve()
|
||||||
|
if not (repository / ".git").exists():
|
||||||
|
raise ValueError("--repository must be a Git working tree.")
|
||||||
|
|
||||||
|
commit = str(git(repository, "rev-parse", "--verify", f"{ref}^{{commit}}")).lower()
|
||||||
|
if FULL_SHA.fullmatch(commit) is None:
|
||||||
|
raise ValueError("The selected ref did not resolve to a full Git commit SHA.")
|
||||||
|
|
||||||
|
dotnet_version, web_version = versions(repository, commit)
|
||||||
|
if dotnet_version != web_version:
|
||||||
|
raise ValueError(
|
||||||
|
f"Committed release versions differ: .NET={dotnet_version}, web={web_version}."
|
||||||
|
)
|
||||||
|
if SEMVER.fullmatch(dotnet_version) is None:
|
||||||
|
raise ValueError("The committed version must use MAJOR.MINOR.PATCH.")
|
||||||
|
|
||||||
|
output = output_directory / f"guestops_{dotnet_version}.tar.gz"
|
||||||
|
if output.exists():
|
||||||
|
raise ValueError("The output package already exists; published versions are not overwritten.")
|
||||||
|
|
||||||
|
with tempfile.TemporaryDirectory(prefix="guestops-release-") as temporary:
|
||||||
|
root = Path(temporary)
|
||||||
|
source = root / "source"
|
||||||
|
release = root / "release"
|
||||||
|
source.mkdir()
|
||||||
|
(release / "api").mkdir(parents=True)
|
||||||
|
(release / "worker").mkdir(parents=True)
|
||||||
|
extract_commit(repository, commit, source)
|
||||||
|
|
||||||
|
runner(["npm", "ci", "--no-audit", "--no-fund"], source / "web")
|
||||||
|
runner(["npm", "run", "build"], source / "web")
|
||||||
|
common = [
|
||||||
|
"--configuration", "Release",
|
||||||
|
"--runtime", LINUX_RUNTIME,
|
||||||
|
"--self-contained", "true",
|
||||||
|
"--no-restore",
|
||||||
|
"-p:UseAppHost=true",
|
||||||
|
"-p:ContinuousIntegrationBuild=true",
|
||||||
|
"-p:Deterministic=true",
|
||||||
|
f"-p:PathMap={source}=/src",
|
||||||
|
]
|
||||||
|
runner(
|
||||||
|
["dotnet", "restore", "src/GuestOps.Api/GuestOps.Api.csproj", "--runtime", LINUX_RUNTIME],
|
||||||
|
source,
|
||||||
|
)
|
||||||
|
runner(
|
||||||
|
["dotnet", "publish", "src/GuestOps.Api/GuestOps.Api.csproj", *common, "--output", str(release / "api")],
|
||||||
|
source,
|
||||||
|
)
|
||||||
|
runner(
|
||||||
|
["dotnet", "restore", "src/GuestOps.Worker/GuestOps.Worker.csproj", "--runtime", LINUX_RUNTIME],
|
||||||
|
source,
|
||||||
|
)
|
||||||
|
runner(
|
||||||
|
["dotnet", "publish", "src/GuestOps.Worker/GuestOps.Worker.csproj", *common, "--output", str(release / "worker")],
|
||||||
|
source,
|
||||||
|
)
|
||||||
|
shutil.copytree(source / "web" / "dist", release / "api" / "wwwroot")
|
||||||
|
|
||||||
|
for required in (release / "api" / "GuestOps.Api", release / "worker" / "GuestOps.Worker"):
|
||||||
|
if not required.is_file():
|
||||||
|
raise ValueError(f"Expected native executable was not produced: {required.name}.")
|
||||||
|
if not (release / "api" / "wwwroot" / "index.html").is_file():
|
||||||
|
raise ValueError("The frontend build did not produce index.html.")
|
||||||
|
|
||||||
|
content = release_bytes(release, dotnet_version)
|
||||||
|
|
||||||
|
output_directory.mkdir(parents=True, exist_ok=True)
|
||||||
|
output.write_bytes(content)
|
||||||
|
return output, {"commit": commit, "version": dotnet_version, "runtime": LINUX_RUNTIME}
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> None:
|
||||||
|
parser = argparse.ArgumentParser(description=__doc__)
|
||||||
|
parser.add_argument("--ref", required=True, help="Exact tag, branch, or full commit to package.")
|
||||||
|
parser.add_argument("--repository", type=Path, default=Path(__file__).resolve().parents[1])
|
||||||
|
parser.add_argument("--output-directory", required=True, type=Path)
|
||||||
|
args = parser.parse_args()
|
||||||
|
try:
|
||||||
|
archive, details = build_package(args.repository, args.ref, args.output_directory)
|
||||||
|
except (OSError, ValueError, ET.ParseError, json.JSONDecodeError, subprocess.SubprocessError) as error:
|
||||||
|
print(f"Release packaging failed: {error}", file=sys.stderr)
|
||||||
|
raise SystemExit(1)
|
||||||
|
print(json.dumps({"archive": str(archive), **details}, indent=2))
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -11,7 +11,7 @@ import re
|
|||||||
|
|
||||||
|
|
||||||
GATE_B = {
|
GATE_B = {
|
||||||
"release-ci", "debian-host", "persistence", "backup-restore", "google-mailbox",
|
"release-package", "debian-host", "persistence", "backup-restore", "google-mailbox",
|
||||||
"automation", "identity-privacy", "inbox-usability", "capacity",
|
"automation", "identity-privacy", "inbox-usability", "capacity",
|
||||||
"incident-support", "pilot-findings",
|
"incident-support", "pilot-findings",
|
||||||
}
|
}
|
||||||
@@ -34,7 +34,7 @@ def timestamp(value: object, field: str) -> dt.datetime:
|
|||||||
|
|
||||||
def validate(record: object) -> None:
|
def validate(record: object) -> None:
|
||||||
require(isinstance(record, dict), "Approval record must be a JSON object.")
|
require(isinstance(record, dict), "Approval record must be a JSON object.")
|
||||||
require(record.get("schemaVersion") == 2, "Unsupported approval schema; Gate B 0.2.0 requires schemaVersion 2.")
|
require(record.get("schemaVersion") == 2, "Unsupported approval schema; Gate B 0.2.2 requires schemaVersion 2.")
|
||||||
gate = record.get("targetGate")
|
gate = record.get("targetGate")
|
||||||
require(gate in ("B", "C"), "targetGate must be B or C.")
|
require(gate in ("B", "C"), "targetGate must be B or C.")
|
||||||
require(record.get("decision") == "approved", "Only an explicit approved decision passes validation.")
|
require(record.get("decision") == "approved", "Only an explicit approved decision passes validation.")
|
||||||
|
|||||||
@@ -1,76 +0,0 @@
|
|||||||
#!/usr/bin/env python3
|
|
||||||
"""Create deterministic evidence for a reviewed GuestOps image archive."""
|
|
||||||
|
|
||||||
from __future__ import annotations
|
|
||||||
|
|
||||||
import argparse
|
|
||||||
import hashlib
|
|
||||||
import json
|
|
||||||
import re
|
|
||||||
from pathlib import Path
|
|
||||||
|
|
||||||
|
|
||||||
ROOT = Path(__file__).resolve().parents[1]
|
|
||||||
|
|
||||||
|
|
||||||
def project_versions() -> tuple[str, str]:
|
|
||||||
props = (ROOT / "Directory.Build.props").read_text(encoding="utf-8")
|
|
||||||
match = re.search(r"<Version>([^<]+)</Version>", props)
|
|
||||||
if match is None:
|
|
||||||
raise ValueError("Directory.Build.props does not contain a Version element")
|
|
||||||
package = json.loads((ROOT / "web" / "package.json").read_text(encoding="utf-8"))
|
|
||||||
return match.group(1), str(package["version"])
|
|
||||||
|
|
||||||
|
|
||||||
def sha256(path: Path) -> str:
|
|
||||||
digest = hashlib.sha256()
|
|
||||||
with path.open("rb") as stream:
|
|
||||||
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
|
|
||||||
digest.update(chunk)
|
|
||||||
return digest.hexdigest()
|
|
||||||
|
|
||||||
|
|
||||||
def main() -> None:
|
|
||||||
parser = argparse.ArgumentParser()
|
|
||||||
parser.add_argument("--artifact", required=True, type=Path)
|
|
||||||
parser.add_argument("--commit", required=True)
|
|
||||||
parser.add_argument("--api-image", required=True)
|
|
||||||
parser.add_argument("--api-id", required=True)
|
|
||||||
parser.add_argument("--worker-image", required=True)
|
|
||||||
parser.add_argument("--worker-id", required=True)
|
|
||||||
parser.add_argument("--output", required=True, type=Path)
|
|
||||||
args = parser.parse_args()
|
|
||||||
|
|
||||||
commit = args.commit.lower()
|
|
||||||
if re.fullmatch(r"[0-9a-f]{40}", commit) is None:
|
|
||||||
parser.error("--commit must be a full 40-character Git SHA")
|
|
||||||
if not args.artifact.is_file():
|
|
||||||
parser.error("--artifact must name an existing file")
|
|
||||||
|
|
||||||
dotnet_version, web_version = project_versions()
|
|
||||||
if dotnet_version != web_version:
|
|
||||||
parser.error(
|
|
||||||
f"release versions differ: .NET={dotnet_version}, web={web_version}"
|
|
||||||
)
|
|
||||||
|
|
||||||
record = {
|
|
||||||
"artifact": {
|
|
||||||
"name": args.artifact.name,
|
|
||||||
"sha256": sha256(args.artifact),
|
|
||||||
"size": args.artifact.stat().st_size,
|
|
||||||
},
|
|
||||||
"commit": commit,
|
|
||||||
"images": {
|
|
||||||
"api": {"id": args.api_id, "reference": args.api_image},
|
|
||||||
"worker": {"id": args.worker_id, "reference": args.worker_image},
|
|
||||||
},
|
|
||||||
"schemaVersion": 1,
|
|
||||||
"version": dotnet_version,
|
|
||||||
}
|
|
||||||
args.output.write_text(
|
|
||||||
json.dumps(record, indent=2, sort_keys=True) + "\n", encoding="utf-8"
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
main()
|
|
||||||
@@ -1,21 +0,0 @@
|
|||||||
[Unit]
|
|
||||||
Description=GuestOps encrypted maintenance backup
|
|
||||||
Requires=docker.service
|
|
||||||
After=docker.service
|
|
||||||
ConditionPathIsDirectory=/srv/guestops
|
|
||||||
ConditionPathIsDirectory=/var/backups/guestops
|
|
||||||
ConditionPathIsDirectory=/var/lib/guestops-backup/gnupg
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
Type=oneshot
|
|
||||||
WorkingDirectory=/srv/guestops
|
|
||||||
EnvironmentFile=/etc/guestops/backup.env
|
|
||||||
Environment=GNUPGHOME=/var/lib/guestops-backup/gnupg
|
|
||||||
UMask=0077
|
|
||||||
ExecStart=/usr/bin/python3 /srv/guestops/deploy/ops.py scheduled-backup --confirm-maintenance
|
|
||||||
NoNewPrivileges=true
|
|
||||||
PrivateTmp=true
|
|
||||||
ProtectHome=true
|
|
||||||
ProtectSystem=full
|
|
||||||
ReadWritePaths=/var/backups/guestops /var/lib/guestops-backup/gnupg
|
|
||||||
TimeoutStartSec=45min
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
[Unit]
|
|
||||||
Description=Run the GuestOps encrypted backup each day
|
|
||||||
|
|
||||||
[Timer]
|
|
||||||
OnCalendar=*-*-* 02:17:00 UTC
|
|
||||||
RandomizedDelaySec=30min
|
|
||||||
Persistent=true
|
|
||||||
Unit=guestops-backup.service
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=timers.target
|
|
||||||
+3
-4
@@ -16,18 +16,17 @@ An email belongs to one hotel account. Existing active accounts cannot be reassi
|
|||||||
|
|
||||||
## Owner recovery on the Linux server
|
## Owner recovery on the Linux server
|
||||||
|
|
||||||
The server administrator must verify the owner's identity before issuing a recovery link. On the server, in the directory containing the deployed Compose file and its private environment file:
|
The server administrator must verify the owner's identity before issuing a recovery link. On the server:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
read -r -p 'Verified owner email: ' RECOVERY_EMAIL
|
read -r -p 'Verified owner email: ' RECOVERY_EMAIL
|
||||||
export RECOVERY_EMAIL
|
sudo -u cms sh -c 'set -a; . /etc/guestops/guestops.env; set +a; RECOVERY_EMAIL="$1" /srv/guestops/api/GuestOps.Api --recover-owner' sh "$RECOVERY_EMAIL"
|
||||||
docker compose run --rm --no-deps -e RECOVERY_EMAIL api --recover-owner
|
|
||||||
unset RECOVERY_EMAIL
|
unset RECOVERY_EMAIL
|
||||||
```
|
```
|
||||||
|
|
||||||
The command uses the configured database, generates a private link, prints it to the administrator's terminal and exits. Share it only with the verified owner. Do not paste it into tickets, chat logs, build logs or source control; avoid running this command in a recorded terminal. It expires in 30 minutes and can be consumed once. Running the command again invalidates the earlier link. Bootstrap remains a create-only command and cannot reset passwords.
|
The command uses the configured database, generates a private link, prints it to the administrator's terminal and exits. Share it only with the verified owner. Do not paste it into tickets, chat logs, build logs or source control; avoid running this command in a recorded terminal. It expires in 30 minutes and can be consumed once. Running the command again invalidates the earlier link. Bootstrap remains a create-only command and cannot reset passwords.
|
||||||
|
|
||||||
`PublicUrl` must be the configured HTTPS origin, normally `https://sandbox-guestops.futuresens.co.uk`. Request Host headers never determine recovery-link origins. The Development-only preview uses `http://127.0.0.1:5173`.
|
`PublicUrl` must be the configured HTTPS origin, such as `https://sandbox-guestops.futuresens.co.uk`. Request Host headers never determine recovery-link origins. The Development-only preview uses `http://127.0.0.1:5173`.
|
||||||
|
|
||||||
## Storage and session behavior
|
## Storage and session behavior
|
||||||
|
|
||||||
|
|||||||
@@ -12,7 +12,7 @@ The first version requires a top-level plain-text MIME message. HTML and multipa
|
|||||||
|
|
||||||
## Enable live mode after acceptance
|
## Enable live mode after acceptance
|
||||||
|
|
||||||
Keep `AUTO_REPLY_ENABLE_LIVE=false` in the deployment `.env` until the Google send/reconciliation workflow and FAQ test-mode results have been accepted. Then set it true and restart both API and worker. Gmail sending must be configured, the hotel must enable staff sending, and the mailbox must have send consent. Finally, the owner explicitly confirms test-mode acceptance and selects **Enable live replies**.
|
Keep `AutoReply__EnableLive=false` in `/etc/guestops/guestops.env` until the Google send/reconciliation workflow and FAQ test-mode results have been accepted. Then set it true and restart `guestops-api.service` and `guestops-worker.service`. Gmail sending must be configured, the hotel must enable staff sending, and the mailbox must have send consent. Finally, the owner explicitly confirms test-mode acceptance and selects **Enable live replies**.
|
||||||
|
|
||||||
Before test-mode acceptance, use **Batch safety evaluation** with representative synthetic cases. Each JSON case has a unique `id`, `subject`, `body`, `expectedMatch`, and optionally `expectedKnowledgeId`. The no-send evaluator accepts 1–100 cases, reads the hotel's current reviewed rules and knowledge, and reports false positives, false negatives and per-case reasons without saving a conversation or consuming a quota.
|
Before test-mode acceptance, use **Batch safety evaluation** with representative synthetic cases. Each JSON case has a unique `id`, `subject`, `body`, `expectedMatch`, and optionally `expectedKnowledgeId`. The no-send evaluator accepts 1–100 cases, reads the hotel's current reviewed rules and knowledge, and reports false positives, false negatives and per-case reasons without saving a conversation or consuming a quota.
|
||||||
|
|
||||||
|
|||||||
+60
-68
@@ -1,89 +1,81 @@
|
|||||||
# Debian sandbox deployment
|
# GuestOps deployment
|
||||||
|
|
||||||
Target: `https://sandbox-guestops.futuresens.co.uk`. These are reviewable deployment instructions; creating these files does not deploy or change the server.
|
GuestOps is deployed by the central Futuresens Ansible repository. Sandbox is
|
||||||
|
`https://sandbox-guestops.futuresens.co.uk` and production is
|
||||||
|
`https://guestops.futuresens.co.uk`.
|
||||||
|
|
||||||
## 1. Prepare the host
|
## Prepare a version
|
||||||
|
|
||||||
Check the existing Nginx, Docker, MongoDB and firewall configuration before installation. Preserve existing services. The provided Compose file creates a dedicated MongoDB instance for GuestOps with no host port; if MongoDB already exists on the host, use a reviewed private connection and application-scoped user instead of starting a conflicting instance.
|
The .NET version in `Directory.Build.props` and the frontend version in
|
||||||
|
`web/package.json` must match. Test the committed revision, then package it:
|
||||||
Install Docker Engine/Compose and Nginx using their official Debian instructions. Keep SSH access unchanged. Only HTTPS/HTTP for this hostname need public access; port 8080 is loopback-only and MongoDB has no published port.
|
|
||||||
|
|
||||||
Clone the private repository using an authorized GitHub account. Place the checkout in a dedicated application directory. Copy `.env.example` to `.env`, set permissions to 600, and fill two different MongoDB passwords generated with `openssl rand -hex 32`. Use hex values so they are safe in the MongoDB URI. Store real values only on the server or in its secret-management system.
|
|
||||||
|
|
||||||
The MongoDB initialization script runs only on a new volume. Changing `.env` later does not rotate existing database users. Rotate those credentials through MongoDB administration and update application configuration together.
|
|
||||||
|
|
||||||
## 2. Load reviewed application images
|
|
||||||
|
|
||||||
CI builds API and worker images and packages them in a `guestops-linux-*` artifact. Download the successful artifact for the desired commit and transfer it to the sandbox through your normal authorized deployment process.
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
docker load -i guestops-images.tar.gz
|
dotnet run --project tests/GuestOps.Tests
|
||||||
|
python3 -m unittest discover -s tests -p "test_*.py"
|
||||||
|
cd web && npm ci && npm run build && cd ..
|
||||||
|
|
||||||
|
python3 deploy/package_release.py \
|
||||||
|
--ref FULL_COMMIT_OR_TAG \
|
||||||
|
--output-directory ../ansible/playbooks/files/guestops
|
||||||
```
|
```
|
||||||
|
|
||||||
Set `GUESTOPS_API_IMAGE=guestops-api:<commit-sha>` and `GUESTOPS_WORKER_IMAGE=guestops-worker:<commit-sha>` in `.env` using that exact build's SHA. Then run:
|
For version `0.2.2`, this creates `guestops_0.2.2.tar.gz`. The archive contains
|
||||||
|
self-contained Linux x64 API and worker applications, including the built
|
||||||
|
frontend. Published version files are immutable; change the application version
|
||||||
|
before making another archive.
|
||||||
|
|
||||||
|
## Configure Ansible
|
||||||
|
|
||||||
|
The server group needs only the application switch, version and subdomain:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
hasguestops: true
|
||||||
|
guestopsversion: "0.2.2"
|
||||||
|
guestopssubdomain: "sandbox-guestops"
|
||||||
|
```
|
||||||
|
|
||||||
|
Production uses `guestopssubdomain: "guestops"`. The native services use the
|
||||||
|
existing MongoDB service on `127.0.0.1:27017`. Google sending,
|
||||||
|
automatic live replies, AI, PMS connections, and payment connections remain
|
||||||
|
disabled until they are configured separately.
|
||||||
|
|
||||||
|
## Deploy
|
||||||
|
|
||||||
|
Deploy sandbox first:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
docker compose config --quiet
|
ansible-playbook playbooks/guestops.yml -K \
|
||||||
docker compose up -d --no-build
|
--extra-vars "thehost=sandbox"
|
||||||
curl --fail http://127.0.0.1:8080/health
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Do not run `docker compose config` without `--quiet` in shared logs: expanded configuration contains secrets. Local image builds are available with Compose for development, but CI builds avoid consuming sandbox resources.
|
After acceptance, deploy the same versioned archive to production:
|
||||||
|
|
||||||
## 3. Provision the first hotel owner
|
|
||||||
|
|
||||||
The API has an administrative bootstrap command. It creates one hotel and one owner, refuses an existing email address, and does not reset passwords. Run it with environment variables passed from a private terminal; do not put the password directly in shell history or a repository file.
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
read -r -p 'Owner email: ' BOOTSTRAP_EMAIL
|
ansible-playbook playbooks/guestops.yml -K \
|
||||||
read -r -p 'Hotel name: ' BOOTSTRAP_HOTEL
|
--extra-vars "thehost=dbserver"
|
||||||
read -r -s -p 'Owner password (14+ characters): ' BOOTSTRAP_PASSWORD
|
|
||||||
printf '\n'
|
|
||||||
export BOOTSTRAP_EMAIL BOOTSTRAP_HOTEL BOOTSTRAP_PASSWORD
|
|
||||||
docker compose run --rm --no-deps -e BOOTSTRAP_EMAIL -e BOOTSTRAP_HOTEL -e BOOTSTRAP_PASSWORD api --bootstrap
|
|
||||||
unset BOOTSTRAP_EMAIL BOOTSTRAP_HOTEL BOOTSTRAP_PASSWORD
|
|
||||||
```
|
```
|
||||||
|
|
||||||
There is no development/demo account in production. Owners can issue staff invitation and assisted recovery links through Team; see [account setup](accounts.md). Passwords must be 14–128 characters. Public self-registration is not enabled.
|
The playbook stops the existing systemd services, replaces `/srv/guestops`,
|
||||||
|
renders its environment configuration, starts the self-contained API and worker,
|
||||||
|
and manages its Nginx site. It serves HTTP before the certificate exists and
|
||||||
|
switches the site to HTTPS after Certbot has created the certificate. Port 8080
|
||||||
|
remains loopback-only and `/var/lib/guestops/keys` survives redeployment.
|
||||||
|
|
||||||
## 4. Configure HTTPS
|
On the first deployment, create the certificate after the HTTP site is available:
|
||||||
|
|
||||||
Verify the hostname's DNS resolves to this server. Obtain a valid certificate for it using your existing ACME/Certbot process. The Nginx example expects a Let's Encrypt certificate. For first issuance, configure the port-80 ACME location before enabling the port-443 block; do not point Nginx at missing certificate files.
|
|
||||||
|
|
||||||
Merge `deploy/nginx.conf` into the existing host configuration, check with `nginx -t`, then reload Nginx. Confirm HTTPS serves the login page. API cookies are always Secure outside preview mode; logging in through plain HTTP is intentionally unsupported.
|
|
||||||
|
|
||||||
Compose reserves the private bridge `172.30.87.0/24`, with gateway `172.30.87.1`. The API trusts the host gateway's `X-Forwarded-Proto` header so Nginx's HTTPS connections receive secure session and CSRF cookies. Check for an existing network using that range. If it conflicts, set both `GUESTOPS_SUBNET` and `GUESTOPS_GATEWAY` in `.env` to a free matching subnet and gateway. Do not replace this with unrestricted forwarded-header trust.
|
|
||||||
|
|
||||||
The login rate limiter uses the client address forwarded by the explicitly configured host proxy (10 attempts per client address per minute). ASP.NET accepts one forwarding hop only from `Proxy__KnownAddress`; arbitrary client-supplied forwarding headers are not trusted. Keep the API port loopback-only and update the known address together with any reviewed Compose subnet change.
|
|
||||||
|
|
||||||
## 5. Configure Google
|
|
||||||
|
|
||||||
Create or select your Google Cloud project, enable Gmail API, and configure a Web application OAuth client. Register this exact redirect URI:
|
|
||||||
|
|
||||||
`https://sandbox-guestops.futuresens.co.uk/api/integrations/google/callback`
|
|
||||||
|
|
||||||
Configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in the server's `.env` and recreate the API/worker services. Sign in as hotel owner, open Settings and connect a dedicated test mailbox. By default the only requested Gmail scope is `gmail.readonly`. Optional staff-approved sending adds `gmail.send` after server configuration and reconnection; see [AI drafts and reply delivery](replies.md).
|
|
||||||
|
|
||||||
OAuth requests expire after ten minutes, are bound to the signed-in user and hotel, and can be consumed once. Refresh tokens are protected with ASP.NET Data Protection. API and worker share the private persistent key volume; back it up securely with the database. Losing it prevents existing mailbox tokens and sessions from being decrypted. Filesystem protection for the key volume is required; it is separate from MongoDB and must not be publicly served or committed.
|
|
||||||
|
|
||||||
A multi-hotel production launch using Gmail restricted scopes requires planning for Google's verification/security-assessment requirements. This implementation does not bypass those requirements. See [Google restricted-scope verification](https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification).
|
|
||||||
|
|
||||||
## 6. Acceptance and rollback
|
|
||||||
|
|
||||||
Verify separate hotels cannot read or edit each other's records; save and reload settings; restart services and confirm persistence; import test messages twice without duplicates; check the worker resumes a paginated import; confirm no mail is sent without explicit staff approval and that default-disabled sending remains blocked. Review the activity log and Google account used by the connection.
|
|
||||||
|
|
||||||
Keep reviewed image IDs and release images for rollback and backups of both MongoDB and the key volume. Do not remove named volumes to fix application errors. The initial release has no automatic schema migration that destroys data. Use the [operational preflight, encrypted backup and isolated restore drill](operations.md), and establish retention and off-server copies before importing real guest data. `/health/ready` checks database reachability; the owner's Workspace health page also reports worker heartbeat and mailbox/reply exceptions.
|
|
||||||
|
|
||||||
Before accepting the host, run the confirmation-gated persistence drill during an announced maintenance window:
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python3 deploy/ops.py preflight
|
sudo certbot --nginx \
|
||||||
python3 deploy/ops.py persistence-drill --confirm-restart
|
-d sandbox-guestops.futuresens.co.uk \
|
||||||
python3 deploy/ops.py preflight
|
--non-interactive \
|
||||||
|
--agree-tos \
|
||||||
|
-m dmccallum@futuresens.co.uk \
|
||||||
|
--redirect
|
||||||
```
|
```
|
||||||
|
|
||||||
The drill restarts MongoDB, API and worker, then force-recreates the stateless application containers using the already selected images. It verifies that the resolved database and key volumes keep the same identities, MongoDB collection counts and indexes remain unchanged, a value protected before restart can still be decrypted, and loopback readiness recovers. It does not alter provider feature flags, upgrade images, validate public TLS, or replace the separate backup/restore drill.
|
For production, use `-d guestops.futuresens.co.uk`. Certbot obtains and renews the
|
||||||
|
certificate. Rerun the GuestOps playbook after initial certificate creation so
|
||||||
|
Ansible writes the final HTTPS proxy configuration.
|
||||||
|
|
||||||
Record the host, operator, start/end time, release record checksum, resolved image IDs, preflight output and drill result in the deployment acceptance record. Also verify Docker starts at boot and perform a controlled Debian reboot before Gate A approval. After reboot, run the online preflight and inspect the Workspace health page; do not infer worker health solely from API readiness.
|
To roll back, select an older retained native `guestopsversion` (version 0.2.2 or
|
||||||
|
later) in group vars and run the same playbook. MongoDB backup, Filebeat, certificate
|
||||||
The supplied Docker `json-file` logs are size-capped to protect the small pilot disk, but container recreation removes that container's local log history. Before host acceptance, route GuestOps and Nginx logs to the site's durable restricted logging system, or use a reviewed Docker logging override backed by persistent systemd journal storage. Prove that operators can retrieve pre-recreation logs without exposing request credentials or OAuth callback query strings. Central retention and alerting are completed under milestone 11.
|
renewal, and host monitoring are provided by the existing central infrastructure.
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Gate B automation, identity and privacy acceptance
|
# Gate B automation, identity and privacy acceptance
|
||||||
|
|
||||||
Run these reviews against the exact `0.2.0` candidate on the accepted HTTPS sandbox. Keep guest data, staff addresses, provider agreements, screenshots and raw reports in the restricted evidence store. Repository records contain opaque references only.
|
Run these reviews against the exact `0.2.2` candidate on the accepted HTTPS sandbox. Keep guest data, staff addresses, provider agreements, screenshots and raw reports in the restricted evidence store. Repository records contain opaque references only.
|
||||||
|
|
||||||
## Knowledge, AI and FAQ automation
|
## Knowledge, AI and FAQ automation
|
||||||
|
|
||||||
|
|||||||
@@ -6,7 +6,7 @@ Keep screenshots, Gmail message source, provider console records and request dia
|
|||||||
|
|
||||||
## Preparation and stop conditions
|
## Preparation and stop conditions
|
||||||
|
|
||||||
Record the release commit, release-record SHA-256, image IDs, environment, operator, approver and maintenance window. Use two dedicated Google test accounts so the different-account rejection can be exercised without a personal account. Send only clearly synthetic messages between controlled recipients.
|
Record the deployed GuestOps version, environment, operator, approver and maintenance window. Use two dedicated Google test accounts so the different-account rejection can be exercised without a personal account. Send only clearly synthetic messages between controlled recipients.
|
||||||
|
|
||||||
Start with AI drafts, staff sending, FAQ live mode, PMS writes and payment creation disabled. Confirm the OAuth redirect URI exactly matches the HTTPS sandbox. Stop immediately if a mailbox appears under the wrong hotel, a recipient differs from the review screen, an unapproved message is sent, a duplicate is observed, provider output exposes credentials, or an uncertain outcome is about to be blindly retried. Preserve evidence and follow the incident process.
|
Start with AI drafts, staff sending, FAQ live mode, PMS writes and payment creation disabled. Confirm the OAuth redirect URI exactly matches the HTTPS sandbox. Stop immediately if a mailbox appears under the wrong hotel, a recipient differs from the review screen, an unapproved message is sent, a duplicate is observed, provider output exposes credentials, or an uncertain outcome is about to be blindly retried. Preserve evidence and follow the incident process.
|
||||||
|
|
||||||
|
|||||||
@@ -17,7 +17,7 @@ For Gate C, also exercise `pms-ambiguous-write` and `payment-ambiguous-create`.
|
|||||||
|
|
||||||
## Record and validation
|
## Record and validation
|
||||||
|
|
||||||
Copy `deploy/incident-exercise.example.json` into the restricted acceptance store. Bind it to the same full release commit and release-record SHA-256 used by the deployment and pilot decision. Replace the example timestamps, people, targets and evidence references. Change a scenario to `pass` only after its evidence has been independently reviewed. The example is intentionally invalid because its scenarios are `not-run`.
|
Copy `deploy/incident-exercise.example.json` into the restricted acceptance store and record the deployed GuestOps version and environment. Replace the example timestamps, people, targets and evidence references. Change a scenario to `pass` only after its evidence has been independently reviewed. The example is intentionally invalid because its scenarios are `not-run`.
|
||||||
|
|
||||||
For a Gate C exercise, set `targetGate` to `C` and add the PMS and payment scenario records. Validate the completed record with:
|
For a Gate C exercise, set `targetGate` to `C` and add the PMS and payment scenario records. Validate the completed record with:
|
||||||
|
|
||||||
|
|||||||
+3
-3
@@ -42,11 +42,11 @@ Implemented owner-only disconnect/reconnect and import restart controls, synchro
|
|||||||
|
|
||||||
## Milestone 8: operational readiness
|
## Milestone 8: operational readiness
|
||||||
|
|
||||||
Implemented owner-only workspace health, database readiness, worker heartbeat, Linux deployment preflight, maintenance-window encrypted database/key/configuration backup and an isolated restore drill. The drill verifies collection counts, indexes and actual key decryption. Scheduling, off-server copies and production disaster cutover remain operator tasks; the Debian server rehearsal is still required. See [operations and recovery](operations.md).
|
The application provides owner-only workspace health, database readiness and worker heartbeat information. Filebeat, MongoDB backup, host monitoring and disaster recovery are owned by the existing central infrastructure rather than duplicated inside GuestOps. GuestOps runs as native systemd services.
|
||||||
|
|
||||||
## Remaining milestones
|
## Remaining milestones
|
||||||
|
|
||||||
1. Run dedicated Google test-mailbox acceptance, add full thread aggregation and history repair, and rehearse server backup/restore before the first hotel pilot.
|
1. Run dedicated Google test-mailbox acceptance, add full thread aggregation and history repair, and confirm the central server backup/restore process before the first hotel pilot.
|
||||||
2. Add verified transactional email for invitations and recovery notifications, MFA, granular roles and user preferences.
|
2. Add verified transactional email for invitations and recovery notifications, MFA, granular roles and user preferences.
|
||||||
3. Run a representative live AI draft evaluation, improve retrieval and evidence presentation, and approve the selected provider data-processing arrangements.
|
3. Run a representative live AI draft evaluation, improve retrieval and evidence presentation, and approve the selected provider data-processing arrangements.
|
||||||
4. Extend the implemented durable reply queue with operator recovery tooling and broaden the controlled FAQ rules only after live acceptance. Preserve the rule that uncertain sends are never blindly replayed.
|
4. Extend the implemented durable reply queue with operator recovery tooling and broaden the controlled FAQ rules only after live acceptance. Preserve the rule that uncertain sends are never blindly replayed.
|
||||||
@@ -56,7 +56,7 @@ Windows DPAPI settings must not be copied to Linux as usable credentials. Re-ent
|
|||||||
|
|
||||||
## Capacity and operations
|
## Capacity and operations
|
||||||
|
|
||||||
Target supplied by the owner: Debian 12, 4 CPU cores, 7.6 GiB RAM, 18 GiB free disk; MongoDB on the same machine. Compose includes conservative starting memory limits and capped logs, not a capacity guarantee. Keep database/key backups off-server and do not import entire mailboxes by default. Establish retention and restore testing before real guest data is used.
|
Target supplied by the owner: Debian 12, 4 CPU cores, 7.6 GiB RAM, 18 GiB free disk; MongoDB on the same machine. The native API and worker write to the systemd journal; their resource use must be confirmed during sandbox acceptance. Keep database/key backups off-server and do not import entire mailboxes by default. Establish retention and restore testing before real guest data is used.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -1,127 +0,0 @@
|
|||||||
# Operations and recovery
|
|
||||||
|
|
||||||
The owner-only **Workspace health** page reports database reachability, the worker's last heartbeat, mailbox recovery counts and reply exceptions. A heartbeat older than three minutes is marked stale. It proves that the worker process recently reached MongoDB, not that every provider or job succeeded. Reply totals cover at most the latest 500 conversations in this hotel. The page does not verify backups. `/health/ready` returns only readiness status and HTTP 503 when the database cannot be reached.
|
|
||||||
|
|
||||||
## Release evidence and rollback
|
|
||||||
|
|
||||||
Every non-pull-request CI build packages the API and worker images under the full Git commit SHA. The accompanying `release-record.json` binds the archive checksum, application version, commit, image references and immutable Docker image IDs. Retain both files together in restricted off-host release storage; the CI artifact is a transfer mechanism, not the permanent archive.
|
|
||||||
|
|
||||||
Before deployment, verify the archive against its record without loading it:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
python3 - <<'PY'
|
|
||||||
import hashlib, json, pathlib
|
|
||||||
r = json.load(open('release-record.json', encoding='utf-8'))
|
|
||||||
p = pathlib.Path(r['artifact']['name'])
|
|
||||||
assert hashlib.sha256(p.read_bytes()).hexdigest() == r['artifact']['sha256']
|
|
||||||
print(r['commit'], r['version'], r['images'])
|
|
||||||
PY
|
|
||||||
```
|
|
||||||
|
|
||||||
Load the archive, verify each loaded image ID matches the record, set `GUESTOPS_API_IMAGE` and `GUESTOPS_WORKER_IMAGE` to the recorded full-SHA references, and run the deployment preflight. Record the CI run, commit, checksum and operator in the change ticket. A release tag is an approval marker; do not move or reuse an existing tag. The application and web versions must match before the record can be created.
|
|
||||||
|
|
||||||
For rollback, first disable worker-driven external writes and reconcile any sending, payment or PMS operation that may have completed since the prior release. Confirm the previous release archive and record are retained, verify its checksum and image IDs, take an encrypted backup, then select the previous recorded image references in `.env` and recreate only the API and worker. Do not roll back MongoDB or the key volume merely to change application images. Run the online preflight, readiness check and read-only smoke test before re-enabling the worker or provider writes. If a release introduced an incompatible data change, follow its release-specific recovery plan rather than starting an older image against newer data.
|
|
||||||
|
|
||||||
## Deployment preflight
|
|
||||||
|
|
||||||
Run from the dedicated GuestOps checkout on Linux with Python 3.11 or later, Docker with Compose, and GnuPG installed. The tool supports the supplied three-service Compose deployment and the `guestops` database only. Docker access is administrator-equivalent; use the designated server operator account. Load the reviewed API, worker and MongoDB images first, configure `.env` with mode 600, and follow [deployment](deployment.md).
|
|
||||||
|
|
||||||
```sh
|
|
||||||
python3 deploy/ops.py preflight --offline
|
|
||||||
# After Nginx, DNS, TLS and services are running:
|
|
||||||
python3 deploy/ops.py preflight
|
|
||||||
```
|
|
||||||
|
|
||||||
Preflight checks production settings, shared persistent keys, unpublished MongoDB/worker ports, a loopback API port, required images and mounts, private secret files, and at least 8 GiB free disk. The online check also verifies the configured HTTPS readiness URL. This is not a firewall, capacity or provider acceptance test. Allow additional disk space for the database, images and temporary backup/restore files; the supplied server initially had 18 GiB free.
|
|
||||||
|
|
||||||
Configured provider files must be readable by the API container's `app` user while inaccessible to other users. Set their ownership to that image's application UID and mode 600, and run the backup as an authorized operator able to read them (for example root with its designated public GPG keyring). Keep their parent directory private. Empty shipped example files contain no credentials and do not need this ownership change. Check the UID in the reviewed image rather than assuming it matches your host login.
|
|
||||||
|
|
||||||
## Encrypted backup
|
|
||||||
|
|
||||||
Keep the recovery private key on an administrator-controlled recovery machine, with a securely stored passphrase and a second protected recovery copy. Import only its public key on the server and verify its full 40-character fingerprint through a trusted channel. The tool selects that exact fingerprint; it does not establish who owns the key. Do not put private keys, decrypted backups or provider secrets in GitHub.
|
|
||||||
|
|
||||||
```sh
|
|
||||||
gpg --import /secure/path/recovery-public.asc
|
|
||||||
gpg --fingerprint
|
|
||||||
install -d -m 700 "$HOME/guestops-backups"
|
|
||||||
read -r -p 'Verified recovery key fingerprint: ' BACKUP_RECIPIENT
|
|
||||||
python3 deploy/ops.py backup --recipient "$BACKUP_RECIPIENT" \
|
|
||||||
--output "$HOME/guestops-backups/guestops-$(date -u +%Y%m%dT%H%M%SZ).tar.gpg" \
|
|
||||||
--confirm-maintenance
|
|
||||||
unset BACKUP_RECIPIENT
|
|
||||||
```
|
|
||||||
|
|
||||||
This command causes a maintenance interruption. It stops the API and worker, temporarily pauses MongoDB's TTL expiry monitor, dumps MongoDB, and saves the shared Data Protection keys and deployed configuration. The configuration includes credentials and provider files, so the entire bundle is encrypted. Services and the previous TTL setting are restored in a `finally` block before encryption finishes. A successful backup message does not prove that restarted services are healthy; run the online preflight afterwards.
|
|
||||||
|
|
||||||
No other application or administrator may write to this database during the snapshot. Standalone MongoDB dumps need coordinated writes for consistency; see the [MongoDB backup guidance](https://www.mongodb.com/docs/v8.0/tutorial/backup-and-restore-tools/). The tool is intentionally limited to the dedicated stack. It requires the hexadecimal MongoDB root password generated in the deployment guide.
|
|
||||||
|
|
||||||
Copy the encrypted file off-server to restricted storage after every successful backup. Retain the exact API, worker and MongoDB images with the release: an image tag alone can change, and the drill requires matching image IDs. Agree the backup schedule, retention and tolerated data loss before a hotel pilot. Scheduling, off-server transfer, deletion and alerting are operator responsibilities in this milestone; none is silently installed.
|
|
||||||
|
|
||||||
### Optional systemd schedule
|
|
||||||
|
|
||||||
The repository includes an opt-in daily systemd service and timer. They are templates, not automatically installed. The service assumes the reviewed checkout is `/srv/guestops` and stages encrypted files in `/var/backups/guestops`; review and change both unit files together if the host uses different paths.
|
|
||||||
|
|
||||||
Create the staging directory and environment file without storing a private key or passphrase on the server:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
sudo install -d -m 700 /var/backups/guestops /var/lib/guestops-backup/gnupg /etc/guestops
|
|
||||||
sudo install -m 600 /dev/null /etc/guestops/backup.env
|
|
||||||
sudoedit /etc/guestops/backup.env
|
|
||||||
sudo env GNUPGHOME=/var/lib/guestops-backup/gnupg gpg --import /secure/path/recovery-public.asc
|
|
||||||
sudo env GNUPGHOME=/var/lib/guestops-backup/gnupg gpg --fingerprint
|
|
||||||
```
|
|
||||||
|
|
||||||
The file contains only these two settings. `BACKUP_RECIPIENT` is the verified 40-character public-key fingerprint already imported into the service account's GPG keyring.
|
|
||||||
|
|
||||||
```text
|
|
||||||
BACKUP_RECIPIENT=0123456789ABCDEF0123456789ABCDEF01234567
|
|
||||||
BACKUP_DIRECTORY=/var/backups/guestops
|
|
||||||
```
|
|
||||||
|
|
||||||
Review the unit sandbox against the host, copy `deploy/systemd/guestops-backup.service` and `.timer` to `/etc/systemd/system`, then validate and test before enabling:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
sudo systemd-analyze verify /etc/systemd/system/guestops-backup.service /etc/systemd/system/guestops-backup.timer
|
|
||||||
sudo systemctl daemon-reload
|
|
||||||
sudo systemctl start guestops-backup.service
|
|
||||||
sudo systemctl status guestops-backup.service
|
|
||||||
sudo systemctl enable --now guestops-backup.timer
|
|
||||||
systemctl list-timers guestops-backup.timer
|
|
||||||
```
|
|
||||||
|
|
||||||
The timer deliberately causes the same brief maintenance interruption as a manual backup. `Persistent=true` runs a missed event after downtime, so choose and communicate the maintenance window. A successful unit only stages an encrypted file locally. Configure an independently monitored off-host transfer, verify the destination checksum, alert on both unit and transfer failure, and test the alert route. Do not add automatic deletion until retention, legal hold and recovery requirements have named owners.
|
|
||||||
|
|
||||||
Temporary plaintext files are held in private directories and removed on normal completion or exceptions. Process termination or power loss can leave temporary data, stopped services or TTL expiry disabled. After an interrupted run, inspect the dedicated project and remove only its identified abandoned temporary directory after securing any recovery material. Restore the recorded TTL setting (normally true) and restart the services:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker compose exec -T mongo mongosh --quiet --nodb --eval 'const c=new Mongo("mongodb://127.0.0.1"); c.getDB("admin").auth(process.env.MONGO_INITDB_ROOT_USERNAME,process.env.MONGO_INITDB_ROOT_PASSWORD); const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:true}); if(!r.ok)quit(1);'
|
|
||||||
docker compose start api worker
|
|
||||||
python3 deploy/ops.py preflight
|
|
||||||
```
|
|
||||||
|
|
||||||
Use the previous value instead of true if TTL expiry was deliberately disabled beforehand. Do not remove production volumes to recover from a failed backup.
|
|
||||||
|
|
||||||
## Isolated restore drill
|
|
||||||
|
|
||||||
Use a trusted encrypted backup and the recovery key on a Linux recovery machine. Unlock the key through the local GPG agent before running the batch command; never pass its passphrase on the command line. Load the exact reviewed images from the backed-up release first.
|
|
||||||
|
|
||||||
```sh
|
|
||||||
python3 deploy/ops.py restore-drill /secure/path/guestops-backup.tar.gpg \
|
|
||||||
--api-image guestops-api:REVIEWED_RELEASE \
|
|
||||||
--mongo-image mongo:8.0
|
|
||||||
```
|
|
||||||
|
|
||||||
The drill decrypts into a private temporary directory, checks the four expected files and their hashes, rejects unsafe archive entries, and verifies that the restored keys decrypt a protected test value. It then restores MongoDB into a newly created container with no external network or published ports and compares every restored collection's count and indexes. TTL expiry is disabled in this disposable database so expired token records do not disappear during comparison. The exact temporary container and its volumes are removed afterwards. No worker or production application is started.
|
|
||||||
|
|
||||||
The decrypted bundle is capped at 8 GiB for this pilot tool. Leave room for the encrypted file, decrypted archive, extracted files and restored database. GPG's [output limit](https://www.gnupg.org/documentation/manuals/gnupg/GPG-Input-and-Output.html) bounds decrypted output; checksums detect corruption, not the identity of the backup creator. Use backups from the trusted operator only. A drill checks counts, indexes and key decryption, not every document's business meaning or live provider connectivity.
|
|
||||||
|
|
||||||
## Actual disaster recovery
|
|
||||||
|
|
||||||
This milestone implements a rehearsal, not an automatic production restore or cutover command. Before real guest data is accepted, rehearse a separate recovery deployment and document its precise image IDs, volume names, secret locations and operator responsibilities.
|
|
||||||
|
|
||||||
Restore into new isolated MongoDB and key volumes; preserve the damaged original for investigation. Reconstruct reviewed configuration from the encrypted bundle without copying old Docker container IDs or blindly executing archived configuration. Restore the `guestops` database with the compatible MongoDB tools and restore the matching key files with the application's required ownership. Check hotel/account records and saved settings before exposing the recovered API. Keep the worker stopped, provider writes disabled and external network access restricted throughout this process.
|
|
||||||
|
|
||||||
**A restored database can predate emails, invoices and PMS changes that providers already completed.** Review pending, sending and uncertain records against provider evidence before enabling any worker, including automatic FAQ rules. Do not replay an older approval merely because the restored record says it is pending. Reconcile external effects, validate account sessions and mailbox authorization, and explicitly approve the cutover only after these checks. Rotate credentials if compromise prompted the recovery. Keep the old deployment stopped when enabling the replacement.
|
|
||||||
|
|
||||||
CI exercises a synthetic encrypted backup and isolated restore drill, including actual key decryption and database comparison. A successful CI drill is separate from the required rehearsal on the Debian server with its actual deployment configuration.
|
|
||||||
|
|
||||||
+2
-2
@@ -23,7 +23,7 @@ Copy `deploy/payments.example.json` to a private `payments.local.json` outside t
|
|||||||
|
|
||||||
Use the internal 32-character hotel ID shown on the Payments page. `MerchantAccount` is an administrator-maintained identity binding: verify it against the merchant account behind the key. Do not reuse the same identity for a different merchant. The API accepts only `https://sandbox.nmi.com` and `https://secure.nmi.com`; confirm the correct environment and key with NMI.
|
Use the internal 32-character hotel ID shown on the Payments page. `MerchantAccount` is an administrator-maintained identity binding: verify it against the merchant account behind the key. Do not reuse the same identity for a different merchant. The API accepts only `https://sandbox.nmi.com` and `https://secure.nmi.com`; confirm the correct environment and key with NMI.
|
||||||
|
|
||||||
Set `PAYMENTS_CONFIG_FILE_HOST` in the deployment `.env` to the absolute private file path. Compose mounts it read-only in the API only. Restrict file permissions to the administrator and the container user/group that needs read access. Determine the image's user with `docker run --rm --entrypoint id YOUR_API_IMAGE -u` before assigning permissions. Restart the API after changes. The default empty example disables the integration. Do not commit private configuration or put keys in the browser.
|
Store the private file as `/etc/guestops/payments.json`, owned by `root:cms` with mode `0640`, and set `Payments__ConfigFile=/etc/guestops/payments.json` in `/etc/guestops/guestops.env`. Only the native API service reads it. Restart `guestops-api.service` after changes. Leaving the setting unset disables the integration. Do not commit private configuration or put keys in the browser or release archive.
|
||||||
|
|
||||||
After sandbox acceptance, enable `CreatesEnabled` on the server and **Allow owner-approved payment invoices** in the hotel's Payments page. Both controls are required. Turning off creation leaves read-only reconciliation available. Key rotation preserves reconciliation for the same merchant binding; pending approvals require the original credential revision and must be replaced after rotation. Changing the merchant identity blocks reconciliation until the original binding is restored.
|
After sandbox acceptance, enable `CreatesEnabled` on the server and **Allow owner-approved payment invoices** in the hotel's Payments page. Both controls are required. Turning off creation leaves read-only reconciliation available. Key rotation preserves reconciliation for the same merchant binding; pending approvals require the original credential revision and must be replaced after rotation. Changing the merchant identity blocks reconciliation until the original binding is restored.
|
||||||
|
|
||||||
@@ -46,6 +46,6 @@ Only unsubmitted proposals can be cancelled in GuestOps. Invoice closure, refund
|
|||||||
|
|
||||||
## Acceptance before live use
|
## Acceptance before live use
|
||||||
|
|
||||||
Automated tests use an in-process fake HTTP handler and never contact NMI. They cover tenant isolation, amount/currency/identity mismatches, partial status, concurrent approvals, lost create responses, pagination and merchant changes. CI checks the production configuration mount and disabled defaults.
|
Automated tests use an in-process fake HTTP handler and never contact NMI. They cover tenant isolation, amount/currency/identity mismatches, partial status, concurrent approvals, lost create responses, pagination and merchant changes. Run the production-configuration and disabled-default checks before packaging and again during the Ansible deployment verification.
|
||||||
|
|
||||||
Use a dedicated sandbox merchant and recipient to validate authentication, supported currency, exact request/response fields, preservation of `order_details.order_id`, customer invoice email and hosted checkout, partial/full payments and interrupted-request recovery. Live acceptance remains pending. Planet, direct payment links in GuestOps replies, automatic booking after payment, automated expiry/closure and background polling are follow-on work.
|
Use a dedicated sandbox merchant and recipient to validate authentication, supported currency, exact request/response fields, preservation of `order_details.order_id`, customer invoice email and hosted checkout, partial/full payments and interrupted-request recovery. Live acceptance remains pending. Planet, direct payment links in GuestOps replies, automatic booking after payment, automated expiry/closure and background polling are follow-on work.
|
||||||
|
|||||||
@@ -1,67 +0,0 @@
|
|||||||
# Supervised pilot, capacity and release approval
|
|
||||||
|
|
||||||
Milestone 18 is an evidence exercise against the exact approved release, not a feature toggle. Use synthetic data for capacity work and a separately approved, tightly supervised hotel cohort for the pilot. Keep provider writes and FAQ live mode disabled until their individual acceptance records are approved.
|
|
||||||
|
|
||||||
Before the pilot, complete the [Gate B automation, identity and privacy acceptance](gate-b-prerequisites.md) as well as the Google and desktop exercises. These reviews must use the same release identifiers as the final decision.
|
|
||||||
|
|
||||||
## Read-only capacity probe
|
|
||||||
|
|
||||||
The capacity probe logs in once with a dedicated sandbox staff account and sends bounded concurrent GET requests to readiness, hotel settings and cursor-paginated inbox endpoints. It never calls provider integrations, creates records, edits drafts or retains response bodies. Run it only during an approved sandbox window and monitor CPU, memory, MongoDB latency, disk, Nginx and application errors independently.
|
|
||||||
|
|
||||||
```sh
|
|
||||||
read -r -p 'Capacity account email: ' CAPACITY_EMAIL
|
|
||||||
read -r -s -p 'Capacity account password: ' CAPACITY_PASSWORD
|
|
||||||
export CAPACITY_EMAIL CAPACITY_PASSWORD
|
|
||||||
python3 deploy/capacity_probe.py \
|
|
||||||
--origin https://sandbox-guestops.futuresens.co.uk \
|
|
||||||
--requests 500 --concurrency 10 \
|
|
||||||
--release-commit FULL_40_CHARACTER_SHA \
|
|
||||||
--release-record-sha256 RELEASE_RECORD_SHA256 \
|
|
||||||
--output /secure/acceptance/capacity.json \
|
|
||||||
--confirm-sandbox
|
|
||||||
unset CAPACITY_EMAIL CAPACITY_PASSWORD
|
|
||||||
```
|
|
||||||
|
|
||||||
For the `0.2.0` Gate B candidate, the approved targets are concurrency 10, p95 latency at or below 500 ms, error rate at or below 1%, and at least 25% CPU and memory headroom on the documented four-core, 7.6 GiB host. The generated result reports HTTP observations, not a pass/fail claim. Repeat after a warm-up, investigate every error, and retain independently captured host metrics with the report. Hash both retained files for the approval record. Do not point the probe at a live hotel or increase its built-in bounds to simulate a denial of service.
|
|
||||||
|
|
||||||
## Five-business-day supervised pilot
|
|
||||||
|
|
||||||
Use one approved hotel and named hotel, technical and rollback owners. Start only after the prerequisite evidence below has passed. Keep PMS writes, payment creation and FAQ live mode disabled. Complete one daily review on each of five business days and stop for tenant leakage, credential exposure, data loss, an unapproved or duplicate send, an unreconciled uncertain send, failed rollback or loss of monitoring.
|
|
||||||
|
|
||||||
Copy `deploy/pilot-run.example.json` to the restricted evidence store and replace all placeholders. Resolve critical and high findings; lower-severity findings may be contained only with an owner, expiry and objective rollback trigger. Validate and hash the final record:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
python3 deploy/pilot_run.py /secure/acceptance/pilot-run.json
|
|
||||||
sha256sum /secure/acceptance/pilot-run.json
|
|
||||||
```
|
|
||||||
|
|
||||||
The example deliberately fails while daily reviews are `not-run`. A structurally valid record does not substitute for the five elapsed business days or independent evidence review.
|
|
||||||
|
|
||||||
## Pilot exit record
|
|
||||||
|
|
||||||
The go/no-go record must bind all evidence to the same release commit and release-record checksum. Record named owners, dates, evidence locations, findings and explicit dispositions for:
|
|
||||||
|
|
||||||
- default-branch CI and immutable release archive;
|
|
||||||
- Debian preflight, HTTPS, persistence and controlled reboot;
|
|
||||||
- encrypted off-host backup and timed isolated restore;
|
|
||||||
- Google mailbox and reviewed-send acceptance;
|
|
||||||
- knowledge, AI and FAQ test-mode evaluation;
|
|
||||||
- identity, privacy, retention and audit review;
|
|
||||||
- inbox pagination, draft protection, timezone and desktop-parity acceptance;
|
|
||||||
- capacity targets, observed host headroom and expected pilot workload;
|
|
||||||
- support, rollback, provider-reconciliation and incident exercises;
|
|
||||||
- every pilot usability or security finding.
|
|
||||||
|
|
||||||
Approval requires separate named decisions from the hotel pilot owner and technical release owner. Gate C additionally requires independently accepted PMS and payment-provider evidence. A conditional approval must identify the containment, owner, expiry and rollback trigger; an unresolved finding is not silently converted into acceptance. Retain the signed decision with the release rather than committing guest, credential or incident data to this repository.
|
|
||||||
|
|
||||||
Copy `deploy/pilot-approval.example.json` into the restricted release store and complete it only after reviewing the referenced evidence. Approval schema version 2 binds the five-day pilot record and both the capacity report and independently captured host metrics. The example is intentionally invalid while its decision is `pending`. For a contained finding, record its named owner, future expiry and objective rollback trigger. Validate the completed record with:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
python3 deploy/pilot_approval.py /secure/acceptance/pilot-approval.json
|
|
||||||
```
|
|
||||||
|
|
||||||
The validator requires the exact Gate B evidence set, or that set plus independently accepted PMS and payment-provider evidence for Gate C. It also verifies that observed concurrency meets the pre-agreed target and that p95 latency and error rate remain within their pre-agreed bounds. Structural validation does not inspect evidence or authorize rollout by itself.
|
|
||||||
|
|
||||||
Complete the [incident and rollback exercise](incident-exercise.md) before marking `incident-support` as passed. Its record must use the same release identifiers and target gate as this decision. Reference the retained exercise record and validator output; do not substitute a local automated-test result for the supervised exercise.
|
|
||||||
|
|
||||||
Complete the [desktop-parity acceptance exercise](desktop-acceptance.md) before marking `inbox-usability` as passed. Bind it to the same release identifiers and retain its independently reviewed record outside the repository.
|
|
||||||
+2
-2
@@ -29,9 +29,9 @@ Copy `deploy/pms.example.json` to a private `pms.local.json` outside your checko
|
|||||||
|
|
||||||
Use the client-credentials grant and property permissions supplied for your OHIP environment. Confirm the note type and notification-location codes with the property. The gateway must be an HTTPS origin, without a path. There is no shared fallback configuration between hotels.
|
Use the client-credentials grant and property permissions supplied for your OHIP environment. Confirm the note type and notification-location codes with the property. The gateway must be an HTTPS origin, without a path. There is no shared fallback configuration between hotels.
|
||||||
|
|
||||||
Set `PMS_CONFIG_FILE_HOST` in the deployment `.env` to the absolute private file path. Compose mounts it read-only into the API; the worker does not receive these credentials. Restrict host permissions to the administrator and the API container's user/group, while allowing that user to read the file. Obtain the image's user ID with `docker run --rm --entrypoint id YOUR_API_IMAGE -u` before assigning permissions. Never put credentials in the browser, repository or an image. Restart the API after configuration changes; this file is not hot-reloaded.
|
Store the private file as `/etc/guestops/pms.json`, owned by `root:cms` with mode `0640`, and set `Pms__ConfigFile=/etc/guestops/pms.json` in `/etc/guestops/guestops.env`. Only the native API service needs these credentials. Never put them in the browser, repository or release archive. Restart `guestops-api.service` after configuration changes; this file is not hot-reloaded.
|
||||||
|
|
||||||
The default deployment mounts an empty example and makes no OHIP calls. Begin with sandbox credentials and `WritesEnabled: false`. Lookups can be tested without enabling writes. After sandbox acceptance, server write enablement and the hotel's owner-controlled MongoDB setting must both be enabled. Every operation still needs individual owner approval.
|
The default deployment does not set a PMS configuration file and makes no OHIP calls. Begin with sandbox credentials and `WritesEnabled: false`. Lookups can be tested without enabling writes. After sandbox acceptance, server write enablement and the hotel's owner-controlled MongoDB setting must both be enabled. Every operation still needs individual owner approval.
|
||||||
|
|
||||||
## Review and recovery
|
## Review and recovery
|
||||||
|
|
||||||
|
|||||||
+3
-3
@@ -5,8 +5,8 @@ This milestone adds AI suggestions and a persistent send queue. It does not enab
|
|||||||
## Enable on the sandbox
|
## Enable on the sandbox
|
||||||
|
|
||||||
1. Deploy the reviewed images using the deployment guide. Existing hotel records default to AI off and sending off.
|
1. Deploy the reviewed images using the deployment guide. Existing hotel records default to AI off and sending off.
|
||||||
2. Set `AI_API_KEY` and `AI_MODEL` in the server's private `.env`. Choose a model available to your OpenAI project that supports the Responses API and strict JSON-schema output. No model is silently selected and no key is stored in frontend code or MongoDB. Only the API container receives the AI key.
|
2. Set `Ai__ApiKey` and `Ai__Model` in the server's private `/etc/guestops/guestops.env`. Choose a model available to your OpenAI project that supports the Responses API and strict JSON-schema output. No model is silently selected and no key is stored in frontend code or MongoDB. Only the API uses the AI key.
|
||||||
3. Recreate API/worker containers. In hotel Settings, the owner can enable AI drafts. The opt-in explains that staff-requested generation sends the message subject/body and selected approved hotel answers to OpenAI. Requests use `store: false`; this does not replace reviewing the provider's data-processing and retention arrangements.
|
3. Restart `guestops-api.service`. In hotel Settings, the owner can enable AI drafts. The opt-in explains that staff-requested generation sends the message subject/body and selected approved hotel answers to OpenAI. Requests use `store: false`; this does not replace reviewing the provider's data-processing and retention arrangements.
|
||||||
4. For sending, set `GOOGLE_ENABLE_SENDING=true`, recreate API/worker, and reconnect Google. The OAuth request then includes `gmail.readonly` and `gmail.send`. An existing read-only refresh token is not assumed to have send permission; the returned grant must explicitly include `gmail.send`.
|
4. For sending, set `GOOGLE_ENABLE_SENDING=true`, recreate API/worker, and reconnect Google. The OAuth request then includes `gmail.readonly` and `gmail.send`. An existing read-only refresh token is not assumed to have send permission; the returned grant must explicitly include `gmail.send`.
|
||||||
5. Enable staff-approved sending in that hotel's Settings. Use a dedicated test mailbox and synthetic guest messages for live acceptance tests before enabling a real hotel mailbox.
|
5. Enable staff-approved sending in that hotel's Settings. Use a dedicated test mailbox and synthetic guest messages for live acceptance tests before enabling a real hotel mailbox.
|
||||||
|
|
||||||
@@ -34,6 +34,6 @@ Current limitations: messages imported before reply headers were stored must be
|
|||||||
|
|
||||||
## Verification
|
## Verification
|
||||||
|
|
||||||
The test suite covers competing workers, send identity/thread headers, invalid recipients, header injection, uncertain outcomes, restart recovery, pre-send token failure, disabling hotel sending, cross-hotel access, Gmail reconciliation mismatches, AI source isolation, invalid citations, escalations and incomplete responses. CI also runs production container login/restart-persistence smoke checks. Live acceptance must additionally verify Google consent, actual threading, grant revocation, a representative AI draft evaluation set and provider error behaviour with the configured accounts.
|
The test suite covers competing workers, send identity/thread headers, invalid recipients, header injection, uncertain outcomes, restart recovery, pre-send token failure, disabling hotel sending, cross-hotel access, Gmail reconciliation mismatches, AI source isolation, invalid citations, escalations and incomplete responses. Run the native-service login and restart-persistence smoke checks before packaging and during Ansible deployment verification. Live acceptance must additionally verify Google consent, actual threading, grant revocation, a representative AI draft evaluation set and provider error behaviour with the configured accounts.
|
||||||
|
|
||||||
Implementation references: [OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs), [Gmail sending](https://developers.google.com/workspace/gmail/api/guides/sending), [Gmail threads](https://developers.google.com/workspace/gmail/api/guides/threads).
|
Implementation references: [OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs), [Gmail sending](https://developers.google.com/workspace/gmail/api/guides/sending), [Gmail threads](https://developers.google.com/workspace/gmail/api/guides/threads).
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
"""Exercise disposable CI containers through the host's trusted proxy address.
|
"""Exercise a disposable native deployment through the host's trusted proxy address.
|
||||||
|
|
||||||
The forwarded HTTPS header simulates Nginx TLS termination; this is never run
|
The forwarded HTTPS header simulates Nginx TLS termination; this is never run
|
||||||
against an existing hotel database. Cookie values and credentials are not logged.
|
against an existing hotel database. Cookie values and credentials are not logged.
|
||||||
@@ -35,7 +35,7 @@ def request(path, method="GET", data=None, expected=200):
|
|||||||
return json.loads(body) if "application/json" in response.headers.get("Content-Type", "") else body
|
return json.loads(body) if "application/json" in response.headers.get("Content-Type", "") else body
|
||||||
|
|
||||||
|
|
||||||
assert "root" in request("/"), "Container must serve the built React interface"
|
assert "root" in request("/"), "Native API must serve the built React interface"
|
||||||
request("/api/hotel", expected=401)
|
request("/api/hotel", expected=401)
|
||||||
session = request("/api/session")
|
session = request("/api/session")
|
||||||
assert session["preview"] is False and session["user"] is None
|
assert session["preview"] is False and session["user"] is None
|
||||||
@@ -60,18 +60,18 @@ assert "securityKey" not in payment_status
|
|||||||
request("/api/payments/controls", "PUT", {"version": 0, "enabled": True}, expected=400)
|
request("/api/payments/controls", "PUT", {"version": 0, "enabled": True}, expected=400)
|
||||||
assert request("/api/payments/requests") == []
|
assert request("/api/payments/requests") == []
|
||||||
hotel = request("/api/hotel")
|
hotel = request("/api/hotel")
|
||||||
assert "root" in request("/account"), "Container must serve account link page"
|
assert "root" in request("/account"), "Native API must serve account link page"
|
||||||
assert len(request("/api/onboarding")["steps"]) == 5
|
assert len(request("/api/onboarding")["steps"]) == 5
|
||||||
team = request("/api/team")
|
team = request("/api/team")
|
||||||
assert all("passwordHash" not in member and "securityStamp" not in member and "accountLinkHash" not in member for member in team)
|
assert all("passwordHash" not in member and "securityStamp" not in member and "accountLinkHash" not in member for member in team)
|
||||||
if "--read" in sys.argv:
|
if "--read" in sys.argv:
|
||||||
assert hotel["signature"] == "Persisted across container restart"
|
assert hotel["signature"] == "Persisted across service restart"
|
||||||
invited = next(member for member in team if member["email"] == "ci-staff@example.invalid")
|
invited = next(member for member in team if member["email"] == "deployment-staff@example.invalid")
|
||||||
assert invited["pending"] and not invited["active"] and invited["linkPurpose"] == "Invite"
|
assert invited["pending"] and not invited["active"] and invited["linkPurpose"] == "Invite"
|
||||||
else:
|
else:
|
||||||
hotel["signature"] = "Persisted across container restart"
|
hotel["signature"] = "Persisted across service restart"
|
||||||
request("/api/hotel", "PUT", hotel)
|
request("/api/hotel", "PUT", hotel)
|
||||||
invite = request("/api/team/invite", "POST", {"name": "CI Staff", "email": "ci-staff@example.invalid"})
|
invite = request("/api/team/invite", "POST", {"name": "Deployment Staff", "email": "deployment-staff@example.invalid"})
|
||||||
assert invite["link"].startswith("https://sandbox-guestops.futuresens.co.uk/account#token=")
|
assert invite["link"].startswith("https://sandbox-guestops.futuresens.co.uk/account#token=")
|
||||||
request("/api/auth/logout", "POST")
|
request("/api/auth/logout", "POST")
|
||||||
request("/api/hotel", expected=401)
|
request("/api/hotel", expected=401)
|
||||||
|
|||||||
@@ -1,26 +0,0 @@
|
|||||||
import importlib.util
|
|
||||||
from pathlib import Path
|
|
||||||
import unittest
|
|
||||||
|
|
||||||
|
|
||||||
spec = importlib.util.spec_from_file_location("capacity_probe", Path(__file__).resolve().parents[1] / "deploy" / "capacity_probe.py")
|
|
||||||
probe = importlib.util.module_from_spec(spec)
|
|
||||||
spec.loader.exec_module(probe)
|
|
||||||
|
|
||||||
|
|
||||||
class CapacityProbeTests(unittest.TestCase):
|
|
||||||
def test_summary_reports_failures_and_nearest_rank_latency(self):
|
|
||||||
report = probe.summarize([(True, 10), (True, 20), (False, 30), (True, 40), (True, 100)], 2)
|
|
||||||
self.assertEqual(report["requests"], 5)
|
|
||||||
self.assertEqual(report["successes"], 4)
|
|
||||||
self.assertEqual(report["failures"], 1)
|
|
||||||
self.assertEqual(report["errorRate"], 0.2)
|
|
||||||
self.assertEqual(report["latencyMs"], {"median": 30, "p95": 100, "maximum": 100})
|
|
||||||
|
|
||||||
def test_summary_rejects_empty_results(self):
|
|
||||||
with self.assertRaisesRegex(ValueError, "At least one"):
|
|
||||||
probe.summarize([], 1)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
unittest.main()
|
|
||||||
@@ -1,186 +0,0 @@
|
|||||||
import contextlib
|
|
||||||
import hashlib
|
|
||||||
import importlib.util
|
|
||||||
import io
|
|
||||||
import json
|
|
||||||
import os
|
|
||||||
from pathlib import Path
|
|
||||||
import tarfile
|
|
||||||
import tempfile
|
|
||||||
import unittest
|
|
||||||
from unittest.mock import patch
|
|
||||||
|
|
||||||
spec = importlib.util.spec_from_file_location("ops", Path(__file__).resolve().parents[1] / "deploy" / "ops.py")
|
|
||||||
ops = importlib.util.module_from_spec(spec)
|
|
||||||
spec.loader.exec_module(ops)
|
|
||||||
|
|
||||||
|
|
||||||
class ArchiveTests(unittest.TestCase):
|
|
||||||
def test_persistence_layout_resolves_shared_keys_and_database(self):
|
|
||||||
config = {
|
|
||||||
"services": {
|
|
||||||
"api": {"volumes": [{"type": "volume", "source": "app-keys", "target": "/var/lib/guestops/keys"}]},
|
|
||||||
"worker": {"volumes": [{"type": "volume", "source": "app-keys", "target": "/var/lib/guestops/keys"}]},
|
|
||||||
"mongo": {"volumes": [{"type": "volume", "source": "mongo-data", "target": "/data/db"}]},
|
|
||||||
},
|
|
||||||
"volumes": {
|
|
||||||
"app-keys": {"name": "guestops_app-keys"},
|
|
||||||
"mongo-data": {"name": "guestops_mongo-data"},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
self.assertEqual(ops.persistence_layout(config), {"keys": "guestops_app-keys", "database": "guestops_mongo-data"})
|
|
||||||
|
|
||||||
def test_persistence_layout_rejects_anonymous_or_split_keys(self):
|
|
||||||
config = {
|
|
||||||
"services": {
|
|
||||||
"api": {"volumes": [{"type": "volume", "source": "api-keys", "target": "/var/lib/guestops/keys"}]},
|
|
||||||
"worker": {"volumes": [{"type": "volume", "source": "worker-keys", "target": "/var/lib/guestops/keys"}]},
|
|
||||||
"mongo": {"volumes": [{"type": "volume", "source": "mongo-data", "target": "/data/db"}]},
|
|
||||||
},
|
|
||||||
"volumes": {"api-keys": {}, "worker-keys": {}, "mongo-data": {}},
|
|
||||||
}
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "key volumes differ"):
|
|
||||||
ops.persistence_layout(config)
|
|
||||||
|
|
||||||
config["services"]["worker"]["volumes"][0] = {"type": "volume", "target": "/var/lib/guestops/keys"}
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "named persistent volume"):
|
|
||||||
ops.persistence_layout(config)
|
|
||||||
|
|
||||||
def test_persistence_drill_requires_explicit_restart_confirmation(self):
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "confirm-restart"):
|
|
||||||
ops.persistence_drill(type("Args", (), {"confirm_restart": False})())
|
|
||||||
|
|
||||||
def test_persistence_drill_restarts_then_recreates_stateless_services(self):
|
|
||||||
compose_calls = []
|
|
||||||
inventory = json.dumps({"bytes": 1, "collections": {"hotels": {"count": 1, "indexes": []}}}).encode()
|
|
||||||
|
|
||||||
def compose(*args, **kwargs):
|
|
||||||
compose_calls.append(args)
|
|
||||||
return b"a" * 30 if args[-1] == "--backup-probe" else b""
|
|
||||||
|
|
||||||
def mongo(script):
|
|
||||||
return inventory if "storageSize" in script else b""
|
|
||||||
|
|
||||||
with patch.object(ops, "configuration", return_value={}), \
|
|
||||||
patch.object(ops, "persistence_layout", return_value={"keys": "keys", "database": "data"}), \
|
|
||||||
patch.object(ops, "volume_identity", side_effect=lambda name: {"name": name, "driver": "local", "scope": "local"}), \
|
|
||||||
patch.object(ops, "compose", side_effect=compose), \
|
|
||||||
patch.object(ops, "mongo", side_effect=mongo), \
|
|
||||||
patch.object(ops, "wait_for", side_effect=lambda action, message: action()), \
|
|
||||||
patch.object(ops, "readiness"):
|
|
||||||
ops.persistence_drill(type("Args", (), {"confirm_restart": True})())
|
|
||||||
|
|
||||||
self.assertIn(("restart", "-t", "150", "mongo"), compose_calls)
|
|
||||||
self.assertIn(("restart", "-t", "150", "api", "worker"), compose_calls)
|
|
||||||
self.assertIn(("up", "-d", "--no-build", "--force-recreate", "api", "worker"), compose_calls)
|
|
||||||
self.assertTrue(any("--verify-backup-probe" in call for call in compose_calls))
|
|
||||||
|
|
||||||
def test_empty_provider_templates_are_not_secret_configuration(self):
|
|
||||||
for section, target in (("Pms", "/run/guestops/pms.json"), ("Payments", "/run/guestops/payments.json")):
|
|
||||||
self.assertFalse(ops.provider_configured({section: {"Hotels": {}}}, target))
|
|
||||||
self.assertTrue(ops.provider_configured({section: {"Hotels": {"fixture": {"Key": "fixture"}}}}, target))
|
|
||||||
self.assertTrue(ops.provider_configured({section: {"Unknown": "fixture"}}, target))
|
|
||||||
|
|
||||||
def bundle(self, root, change=None):
|
|
||||||
files = {name: b"fixture backup data" for name in ops.FILES - {"manifest.json"}}
|
|
||||||
files["manifest.json"] = json.dumps({"format": 1, "sha256": {name: hashlib.sha256(data).hexdigest() for name, data in files.items()}}).encode()
|
|
||||||
target = root / "bundle.tar"
|
|
||||||
with tarfile.open(target, "w") as archive:
|
|
||||||
for name, data in files.items():
|
|
||||||
member = tarfile.TarInfo(name); member.size = len(data)
|
|
||||||
if change:
|
|
||||||
change(member)
|
|
||||||
archive.addfile(member, io.BytesIO(data) if member.isfile() else None)
|
|
||||||
return target
|
|
||||||
|
|
||||||
def test_checked_archive_roundtrip(self):
|
|
||||||
with tempfile.TemporaryDirectory() as temp:
|
|
||||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
|
||||||
self.assertEqual(ops.unpack(self.bundle(root), dest)["format"], 1)
|
|
||||||
|
|
||||||
def test_path_escape_rejected(self):
|
|
||||||
with tempfile.TemporaryDirectory() as temp:
|
|
||||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
|
||||||
def corrupt(member):
|
|
||||||
if member.name == "configuration.json": member.name = "../outside"
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "Unexpected backup members"):
|
|
||||||
ops.unpack(self.bundle(root, corrupt), dest)
|
|
||||||
self.assertFalse((root / "outside").exists())
|
|
||||||
|
|
||||||
def test_symlink_rejected(self):
|
|
||||||
with tempfile.TemporaryDirectory() as temp:
|
|
||||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
|
||||||
def corrupt(member):
|
|
||||||
if member.name == "configuration.json": member.type = tarfile.SYMTYPE; member.linkname = "/etc/passwd"; member.size = 0
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "Invalid or oversized"):
|
|
||||||
ops.unpack(self.bundle(root, corrupt), dest)
|
|
||||||
|
|
||||||
def test_checksum_mismatch_rejected(self):
|
|
||||||
with tempfile.TemporaryDirectory() as temp:
|
|
||||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
|
||||||
with patch.object(ops, "digest", return_value="changed"):
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "checksum"):
|
|
||||||
ops.unpack(self.bundle(root), dest)
|
|
||||||
|
|
||||||
def test_backup_requires_explicit_maintenance(self):
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "confirm-maintenance"):
|
|
||||||
ops.backup(type("Args", (), {"confirm_maintenance": False})())
|
|
||||||
|
|
||||||
def test_scheduled_backup_requires_explicit_maintenance(self):
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "confirm-maintenance"):
|
|
||||||
ops.scheduled_backup(type("Args", (), {"confirm_maintenance": False})())
|
|
||||||
|
|
||||||
@unittest.skipUnless(os.name == "posix", "Linux file permission semantics")
|
|
||||||
def test_scheduled_backup_uses_private_external_directory_and_environment(self):
|
|
||||||
with tempfile.TemporaryDirectory() as parent:
|
|
||||||
directory = Path(parent) / "backups"
|
|
||||||
directory.mkdir(mode=0o700)
|
|
||||||
captured = []
|
|
||||||
with patch.dict(os.environ, {"BACKUP_RECIPIENT": "A" * 40, "BACKUP_DIRECTORY": str(directory)}), \
|
|
||||||
patch.object(ops, "ROOT", Path(parent) / "checkout"), \
|
|
||||||
patch.object(ops, "backup", side_effect=lambda args: captured.append(args)), \
|
|
||||||
patch.object(ops.time, "strftime", return_value="20260929T020000Z"):
|
|
||||||
ops.scheduled_backup(type("Args", (), {"confirm_maintenance": True})())
|
|
||||||
self.assertEqual(captured[0].recipient, "A" * 40)
|
|
||||||
self.assertEqual(Path(captured[0].output), directory / "guestops-20260929T020000Z.tar.gpg")
|
|
||||||
self.assertTrue(captured[0].confirm_maintenance)
|
|
||||||
|
|
||||||
@unittest.skipUnless(os.name == "posix", "Linux file permission semantics")
|
|
||||||
def test_scheduled_backup_rejects_checkout_directory(self):
|
|
||||||
with tempfile.TemporaryDirectory() as parent:
|
|
||||||
checkout = Path(parent) / "checkout"
|
|
||||||
directory = checkout / "backups"
|
|
||||||
directory.mkdir(parents=True, mode=0o700)
|
|
||||||
with patch.dict(os.environ, {"BACKUP_RECIPIENT": "A" * 40, "BACKUP_DIRECTORY": str(directory)}), \
|
|
||||||
patch.object(ops, "ROOT", checkout):
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "outside the application checkout"):
|
|
||||||
ops.scheduled_backup(type("Args", (), {"confirm_maintenance": True})())
|
|
||||||
|
|
||||||
@unittest.skipUnless(os.name == "posix", "Linux file permission semantics")
|
|
||||||
def test_dump_failure_restarts_services_and_ttl(self):
|
|
||||||
with tempfile.TemporaryDirectory() as temp:
|
|
||||||
calls = []
|
|
||||||
def compose(*args, **kwargs):
|
|
||||||
calls.append(args)
|
|
||||||
if args[0] == "ps": return b"a" * 64
|
|
||||||
if "sh" in args: raise RuntimeError("Simulated dump failure")
|
|
||||||
return b""
|
|
||||||
def mongo(script):
|
|
||||||
calls.append((script,))
|
|
||||||
if "getParameter" in script: return b"true"
|
|
||||||
if "storageSize" in script: return b'{"bytes":1,"collections":{}}'
|
|
||||||
return b""
|
|
||||||
def run(args, **kwargs):
|
|
||||||
return b'[{"Image":"sha256:fixture"}]' if "inspect" in args else b""
|
|
||||||
args = type("Args", (), {"confirm_maintenance": True, "recipient": "A" * 40, "output": str(Path(temp) / "backup.gpg")})()
|
|
||||||
with patch.object(ops, "configuration", return_value={}), patch.object(ops, "run", side_effect=run), patch.object(ops, "compose", side_effect=compose), patch.object(ops, "mongo", side_effect=mongo), patch.object(ops, "maintenance_lock", return_value=contextlib.nullcontext()):
|
|
||||||
with self.assertRaisesRegex(RuntimeError, "Simulated dump failure"):
|
|
||||||
ops.backup(args)
|
|
||||||
self.assertIn(("start", "api", "worker"), calls)
|
|
||||||
self.assertTrue(any("ttlMonitorEnabled:true" in call[0] for call in calls))
|
|
||||||
self.assertFalse(Path(args.output).exists())
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
unittest.main()
|
|
||||||
|
|
||||||
@@ -0,0 +1,104 @@
|
|||||||
|
import importlib.util
|
||||||
|
import json
|
||||||
|
from pathlib import Path
|
||||||
|
import subprocess
|
||||||
|
import tarfile
|
||||||
|
import tempfile
|
||||||
|
import unittest
|
||||||
|
|
||||||
|
|
||||||
|
ROOT = Path(__file__).resolve().parents[1]
|
||||||
|
spec = importlib.util.spec_from_file_location("package_release", ROOT / "deploy" / "package_release.py")
|
||||||
|
package_release = importlib.util.module_from_spec(spec)
|
||||||
|
spec.loader.exec_module(package_release)
|
||||||
|
|
||||||
|
|
||||||
|
def run(repository: Path, *arguments: str) -> str:
|
||||||
|
result = subprocess.run(
|
||||||
|
["git", "-C", str(repository), *arguments],
|
||||||
|
check=True,
|
||||||
|
capture_output=True,
|
||||||
|
text=True,
|
||||||
|
)
|
||||||
|
return result.stdout.strip()
|
||||||
|
|
||||||
|
|
||||||
|
class PackageReleaseTests(unittest.TestCase):
|
||||||
|
def repository(self, root: Path, dotnet_version: str = "1.2.3", web_version: str = "1.2.3") -> tuple[Path, str]:
|
||||||
|
repository = root / "repository"
|
||||||
|
(repository / "web").mkdir(parents=True)
|
||||||
|
(repository / "src" / "GuestOps.Api").mkdir(parents=True)
|
||||||
|
(repository / "src" / "GuestOps.Worker").mkdir(parents=True)
|
||||||
|
run(repository, "init")
|
||||||
|
run(repository, "config", "user.name", "GuestOps Test")
|
||||||
|
run(repository, "config", "user.email", "guestops@example.invalid")
|
||||||
|
run(repository, "config", "core.autocrlf", "false")
|
||||||
|
(repository / "Directory.Build.props").write_text(
|
||||||
|
f"<Project><PropertyGroup><Version>{dotnet_version}</Version></PropertyGroup></Project>\n",
|
||||||
|
encoding="utf-8",
|
||||||
|
)
|
||||||
|
(repository / "web" / "package.json").write_text(
|
||||||
|
json.dumps({"version": web_version}) + "\n", encoding="utf-8"
|
||||||
|
)
|
||||||
|
(repository / "application.txt").write_text("committed application\n", encoding="utf-8")
|
||||||
|
run(repository, "add", ".")
|
||||||
|
run(repository, "commit", "-m", "fixture")
|
||||||
|
return repository, run(repository, "rev-parse", "HEAD")
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def fake_builder(arguments, working_directory: Path) -> None:
|
||||||
|
if list(arguments[:3]) == ["npm", "run", "build"]:
|
||||||
|
content = (working_directory.parent / "application.txt").read_text(encoding="utf-8")
|
||||||
|
(working_directory / "dist").mkdir()
|
||||||
|
(working_directory / "dist" / "index.html").write_text(content, encoding="utf-8")
|
||||||
|
if arguments[0:2] == ["dotnet", "publish"]:
|
||||||
|
output = Path(arguments[arguments.index("--output") + 1])
|
||||||
|
executable = "GuestOps.Api" if "GuestOps.Api" in arguments[2] else "GuestOps.Worker"
|
||||||
|
(output / executable).write_bytes(executable.encode("ascii"))
|
||||||
|
|
||||||
|
def test_packages_only_selected_commit_as_native_release(self):
|
||||||
|
with tempfile.TemporaryDirectory() as directory:
|
||||||
|
root = Path(directory)
|
||||||
|
repository, commit = self.repository(root)
|
||||||
|
(repository / "application.txt").write_text("uncommitted change\n", encoding="utf-8")
|
||||||
|
|
||||||
|
archive, details = package_release.build_package(
|
||||||
|
repository, commit, root / "output", self.fake_builder
|
||||||
|
)
|
||||||
|
|
||||||
|
self.assertEqual(archive.name, "guestops_1.2.3.tar.gz")
|
||||||
|
self.assertEqual(details, {"commit": commit, "version": "1.2.3", "runtime": "linux-x64"})
|
||||||
|
with tarfile.open(archive, "r:gz") as package:
|
||||||
|
names = package.getnames()
|
||||||
|
self.assertIn("guestops_1.2.3/api/GuestOps.Api", names)
|
||||||
|
self.assertIn("guestops_1.2.3/worker/GuestOps.Worker", names)
|
||||||
|
index = package.extractfile("guestops_1.2.3/api/wwwroot/index.html")
|
||||||
|
self.assertEqual(index.read().decode("utf-8").strip(), "committed application")
|
||||||
|
self.assertEqual(package.getmember("guestops_1.2.3/api/GuestOps.Api").mode, 0o755)
|
||||||
|
self.assertEqual(package.getmember("guestops_1.2.3/worker/GuestOps.Worker").mode, 0o755)
|
||||||
|
|
||||||
|
def test_same_commit_produces_identical_package(self):
|
||||||
|
with tempfile.TemporaryDirectory() as directory:
|
||||||
|
root = Path(directory)
|
||||||
|
repository, commit = self.repository(root)
|
||||||
|
first, _ = package_release.build_package(repository, commit, root / "first", self.fake_builder)
|
||||||
|
second, _ = package_release.build_package(repository, commit, root / "second", self.fake_builder)
|
||||||
|
self.assertEqual(first.read_bytes(), second.read_bytes())
|
||||||
|
|
||||||
|
def test_rejects_mismatched_versions_and_existing_output(self):
|
||||||
|
with tempfile.TemporaryDirectory() as directory:
|
||||||
|
root = Path(directory)
|
||||||
|
repository, commit = self.repository(root, web_version="1.2.4")
|
||||||
|
with self.assertRaisesRegex(ValueError, "versions differ"):
|
||||||
|
package_release.build_package(repository, commit, root / "output", self.fake_builder)
|
||||||
|
|
||||||
|
with tempfile.TemporaryDirectory() as directory:
|
||||||
|
root = Path(directory)
|
||||||
|
repository, commit = self.repository(root)
|
||||||
|
package_release.build_package(repository, commit, root / "output", self.fake_builder)
|
||||||
|
with self.assertRaisesRegex(ValueError, "not overwritten"):
|
||||||
|
package_release.build_package(repository, commit, root / "output", self.fake_builder)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
unittest.main()
|
||||||
@@ -1,82 +0,0 @@
|
|||||||
import hashlib
|
|
||||||
import json
|
|
||||||
import subprocess
|
|
||||||
import sys
|
|
||||||
import tempfile
|
|
||||||
import unittest
|
|
||||||
from pathlib import Path
|
|
||||||
|
|
||||||
|
|
||||||
ROOT = Path(__file__).resolve().parents[1]
|
|
||||||
|
|
||||||
|
|
||||||
class ReleaseRecordTests(unittest.TestCase):
|
|
||||||
def test_writes_versions_checksum_and_immutable_image_ids(self):
|
|
||||||
with tempfile.TemporaryDirectory() as directory:
|
|
||||||
artifact = Path(directory) / "guestops-images.tar.gz"
|
|
||||||
output = Path(directory) / "release-record.json"
|
|
||||||
artifact.write_bytes(b"reviewed image archive")
|
|
||||||
|
|
||||||
subprocess.run(
|
|
||||||
[
|
|
||||||
sys.executable,
|
|
||||||
str(ROOT / "deploy" / "release_record.py"),
|
|
||||||
"--artifact",
|
|
||||||
str(artifact),
|
|
||||||
"--commit",
|
|
||||||
"a" * 40,
|
|
||||||
"--api-image",
|
|
||||||
"guestops-api:" + "a" * 40,
|
|
||||||
"--api-id",
|
|
||||||
"sha256:api",
|
|
||||||
"--worker-image",
|
|
||||||
"guestops-worker:" + "a" * 40,
|
|
||||||
"--worker-id",
|
|
||||||
"sha256:worker",
|
|
||||||
"--output",
|
|
||||||
str(output),
|
|
||||||
],
|
|
||||||
check=True,
|
|
||||||
)
|
|
||||||
|
|
||||||
record = json.loads(output.read_text(encoding="utf-8"))
|
|
||||||
self.assertEqual(record["version"], "0.2.0")
|
|
||||||
self.assertEqual(record["commit"], "a" * 40)
|
|
||||||
self.assertEqual(record["images"]["api"]["id"], "sha256:api")
|
|
||||||
self.assertEqual(
|
|
||||||
record["artifact"]["sha256"],
|
|
||||||
hashlib.sha256(artifact.read_bytes()).hexdigest(),
|
|
||||||
)
|
|
||||||
|
|
||||||
def test_rejects_abbreviated_commit(self):
|
|
||||||
with tempfile.TemporaryDirectory() as directory:
|
|
||||||
artifact = Path(directory) / "images.tar.gz"
|
|
||||||
artifact.write_bytes(b"fixture")
|
|
||||||
result = subprocess.run(
|
|
||||||
[
|
|
||||||
sys.executable,
|
|
||||||
str(ROOT / "deploy" / "release_record.py"),
|
|
||||||
"--artifact",
|
|
||||||
str(artifact),
|
|
||||||
"--commit",
|
|
||||||
"abc123",
|
|
||||||
"--api-image",
|
|
||||||
"api:test",
|
|
||||||
"--api-id",
|
|
||||||
"sha256:api",
|
|
||||||
"--worker-image",
|
|
||||||
"worker:test",
|
|
||||||
"--worker-id",
|
|
||||||
"sha256:worker",
|
|
||||||
"--output",
|
|
||||||
str(Path(directory) / "record.json"),
|
|
||||||
],
|
|
||||||
capture_output=True,
|
|
||||||
text=True,
|
|
||||||
)
|
|
||||||
self.assertNotEqual(result.returncode, 0)
|
|
||||||
self.assertIn("full 40-character Git SHA", result.stderr)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
unittest.main()
|
|
||||||
Generated
+2
-2
@@ -1,12 +1,12 @@
|
|||||||
{
|
{
|
||||||
"name": "guestops-web",
|
"name": "guestops-web",
|
||||||
"version": "0.2.0",
|
"version": "0.2.2",
|
||||||
"lockfileVersion": 3,
|
"lockfileVersion": 3,
|
||||||
"requires": true,
|
"requires": true,
|
||||||
"packages": {
|
"packages": {
|
||||||
"": {
|
"": {
|
||||||
"name": "guestops-web",
|
"name": "guestops-web",
|
||||||
"version": "0.2.0",
|
"version": "0.2.2",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"lucide-react": "^0.577.0",
|
"lucide-react": "^0.577.0",
|
||||||
"react": "19.2.8",
|
"react": "19.2.8",
|
||||||
|
|||||||
+1
-1
@@ -1 +1 @@
|
|||||||
{"name":"guestops-web","private":true,"version":"0.2.0","type":"module","scripts":{"dev":"vite --host 127.0.0.1","build":"tsc -b && vite build","check":"tsc -b"},"dependencies":{"react":"19.2.8","react-dom":"19.2.8","lucide-react":"^0.577.0"},"devDependencies":{"@types/react":"^19.2.0","@types/react-dom":"^19.2.0","@vitejs/plugin-react":"6.1.1","typescript":"~5.9.3","vite":"8.2.2"}}
|
{"name":"guestops-web","private":true,"version":"0.2.2","type":"module","scripts":{"dev":"vite --host 127.0.0.1","build":"tsc -b && vite build","check":"tsc -b"},"dependencies":{"react":"19.2.8","react-dom":"19.2.8","lucide-react":"^0.577.0"},"devDependencies":{"@types/react":"^19.2.0","@types/react-dom":"^19.2.0","@vitejs/plugin-react":"6.1.1","typescript":"~5.9.3","vite":"8.2.2"}}
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ export function OperationsPage({owner,go}:{owner:boolean;go:(path:string)=>void}
|
|||||||
{error&&<div className="alert" role="alert">{error} The information below may be out of date.</div>}
|
{error&&<div className="alert" role="alert">{error} The information below may be out of date.</div>}
|
||||||
{data&&<>
|
{data&&<>
|
||||||
<p className="small muted">Checked {when(data.checkedAt)}{data.preview?' · Sample workspace':''}</p>
|
<p className="small muted">Checked {when(data.checkedAt)}{data.preview?' · Sample workspace':''}</p>
|
||||||
<section className="settings-card"><h2>Application and worker</h2><div className="mailbox-health"><div><span>Database connection</span><strong>{data.preview?'Temporary preview storage':data.database}</strong></div><div><span>Background worker</span><strong>{data.worker.state==='Reporting'?'Reporting normally':data.worker.state==='Preview'?'Unavailable in preview':data.worker.state==='Stale'?'Heartbeat overdue':'No heartbeat received'}</strong></div><div><span>Last worker heartbeat</span><strong>{when(data.worker.lastSeenAt)}</strong></div></div>{['Stale','NotSeen'].includes(data.worker.state)&&<p className="mailbox-explanation">Ask your server administrator to check the worker container and its database connection. Imports and queued replies may be delayed.</p>}<p className="small muted">A heartbeat confirms the worker process can reach storage. It does not prove that Google, payment or PMS requests are succeeding.</p></section>
|
<section className="settings-card"><h2>Application and worker</h2><div className="mailbox-health"><div><span>Database connection</span><strong>{data.preview?'Temporary preview storage':data.database}</strong></div><div><span>Background worker</span><strong>{data.worker.state==='Reporting'?'Reporting normally':data.worker.state==='Preview'?'Unavailable in preview':data.worker.state==='Stale'?'Heartbeat overdue':'No heartbeat received'}</strong></div><div><span>Last worker heartbeat</span><strong>{when(data.worker.lastSeenAt)}</strong></div></div>{['Stale','NotSeen'].includes(data.worker.state)&&<p className="mailbox-explanation">Ask your server administrator to check the worker service and its database connection. Imports and queued replies may be delayed.</p>}<p className="small muted">A heartbeat confirms the worker process can reach storage. It does not prove that Google, payment or PMS requests are succeeding.</p></section>
|
||||||
<section className="settings-card"><h2>Mailbox connections</h2><div className="mailbox-health"><div><span>Total</span><strong>{data.mailboxes.total}</strong></div><div><span>Connected</span><strong>{data.mailboxes.connected}</strong></div><div><span>Need attention</span><strong>{data.mailboxes.attention}</strong></div></div><button className="button secondary" onClick={()=>go('/settings')}>Review mailbox status</button></section>
|
<section className="settings-card"><h2>Mailbox connections</h2><div className="mailbox-health"><div><span>Total</span><strong>{data.mailboxes.total}</strong></div><div><span>Connected</span><strong>{data.mailboxes.connected}</strong></div><div><span>Need attention</span><strong>{data.mailboxes.attention}</strong></div></div><button className="button secondary" onClick={()=>go('/settings')}>Review mailbox status</button></section>
|
||||||
<section className="settings-card"><h2>Reply delivery</h2><div className="mailbox-health"><div><span>Queued or submitting</span><strong>{data.replies.pending}</strong></div><div><span>Need verification</span><strong>{data.replies.uncertain}</strong></div><div><span>Stopped before sending</span><strong>{data.replies.rejected}</strong></div></div><p className="small muted">Based on {data.replies.sampleSize} recent conversations, up to {data.replies.sampleLimit}. Older deliveries may exist. Verify uncertain results in Gmail before taking further action.</p><div className="form-actions"><button className="button secondary" onClick={()=>go('/inbox')}>Review the inbox</button></div></section>
|
<section className="settings-card"><h2>Reply delivery</h2><div className="mailbox-health"><div><span>Queued or submitting</span><strong>{data.replies.pending}</strong></div><div><span>Need verification</span><strong>{data.replies.uncertain}</strong></div><div><span>Stopped before sending</span><strong>{data.replies.rejected}</strong></div></div><p className="small muted">Based on {data.replies.sampleSize} recent conversations, up to {data.replies.sampleLimit}. Older deliveries may exist. Verify uncertain results in Gmail before taking further action.</p><div className="form-actions"><button className="button secondary" onClick={()=>go('/inbox')}>Review the inbox</button></div></section>
|
||||||
<section className="settings-card"><h2>Backups and recovery</h2><p className="muted">Your server administrator runs encrypted backups and isolated restore drills. Ask them to confirm the latest off-server backup and successful restore test.</p><p className="small muted">This page does not claim a backup exists or that the server is ready for production. Provider acceptance and recovery checks are separate.</p></section>
|
<section className="settings-card"><h2>Backups and recovery</h2><p className="muted">Your server administrator runs encrypted backups and isolated restore drills. Ask them to confirm the latest off-server backup and successful restore test.</p><p className="small muted">This page does not claim a backup exists or that the server is ready for production. Provider acceptance and recovery checks are separate.</p></section>
|
||||||
|
|||||||
Reference in New Issue
Block a user