Automate validated MyAPES deployment to Cloudron after main merges

[bmurphy-apescic]

Context

MyAPES is APES CIC's public resource and tool hub at https://myapes.me.uk/. The repository currently has no automated validation or deployment workflow, GitHub About metadata is incomplete, and the live-site audit found focused routing, metadata, and release-record defects.

The intended outcome is a validated, rollback-aware deployment path for the existing Cloudron LAMP application: pull requests validate the tracked public site, and—after a guarded first production run—subsequent validated merges into protected main deploy only the exact tracked public/ release.

Update classification

• Feature
• Hosting and continuous deployment
• Documentation
• Repository maintenance
• SEO hygiene
• Focused bug fix
• Website type: static HTML/CSS/browser JavaScript with one PHP layout helper in an existing Cloudron LAMP application

Scope

• Populate the repository About description, public URL, and approved topics.
• Rewrite the root README with the public/private service boundary, portable local instructions, Cloudron LAMP layout, release records, support links, and deployment lifecycle.
• Add repository safety/release files and reusable validation, local preview, and deployment scripts.
• Release focused public-site fixes as v3.2.1b:
  • true HTTP 404 handling for missing routes;
  • root-relative branded 404 assets and links;
  • canonical apex and clean trailing-slash redirects;
  • clean internal URLs;
  • three missing meta descriptions;
  • corrected Shelter & Rescue title encoding;
  • synchronized version, changelog, Change Log Hub, footer/template, and sitemap records.
• Add a GitHub Actions workflow that validates pull requests and deploys validated main revisions through a protected production environment.
• Package only tracked public/ content, fail closed on unknown production files, create a pre-deploy backup, stage and atomically swap the release, verify production, and automatically roll back the public tree if verification fails.
• Configure a guarded production environment and protect main once the validation check is available.
• Disable automatic branch deletion until merge and deployment verification are complete.

Non-scope

• No credentials, application identifiers, private Cloudron configuration, environment values, database content, uploads, or generated secrets in tracked files or public GitHub records.
• No GitHub Release or tag.
• No database migration, Redis/LDAP/email change, Cloudron package update, service replacement, custom container, or deployment to another app.
• No broad layout refactor, inherited agent-template cleanup, IDE untracking, QA screenshot pruning, licence decision, or invented private security-reporting route.
• No site-wide Open Graph/Twitter/JSON-LD/CSP/Permissions Policy work.
• No new 403, 500, offline, or maintenance pages.

Hosting and public-root constraints

• The existing target is a Cloudron LAMP application.
• Only public/ is deployable and maps to /app/data/public.
• Cloudron-managed siblings under /app/data must remain untouched.
• The public site has no current database-backed runtime, daemon, worker, or scheduler.
• Production access values will be stored only as GitHub production environment secrets named CLOUDRON_FQDN, CLOUDRON_TOKEN, and CLOUDRON_APP_ID.

Security, privacy, and UK GDPR

• This work introduces no new personal-data collection or processing.
• Preserve the boundary between public signposting and protected case, account, complaint, and data-request workflows.
• Use least-privilege production automation credentials and never expose their values in code, logs, issues, pull requests, or documentation.
• Pull-request jobs must not receive production secrets.
• Deployment must preserve non-public Cloudron content and fail closed if the target inventory or application identity is unexpected.
• Existing private vulnerability-reporting and licence gaps are recorded as deferred repository-health work rather than being fabricated here.

Rollback and operational safety

• Reject stale queued deployments before production mutation.
• Verify the exact intended app identity, location, LAMP package, installation, run, and health state.
• Reject unknown public files against a managed-file manifest.
• Create and complete an app backup before changing the public tree.
• Upload one verified archive, extract outside the web root, validate it, retain the previous public release, and swap directories.
• On failed post-deployment checks, restore the previous public release and recheck it while leaving the workflow failed.
• Retain the Cloudron backup as the durable manual restore path.

Acceptance criteria

• GitHub About description, URL, and approved topics are set and re-read.
• README is accurate, portable, linked, timestamped, and contains no private deployment values or obsolete machine path.
• Root safety/release files and reusable validation, preview, and deployment scripts are present.
• Public defects are fixed and all version/release records are synchronized at v3.2.1b.
• Local validation and browser route preview pass, or exact blockers are recorded.
• Pull-request workflow completes with the stable Validate website check passing.
• main requires pull requests, one approval, current validation, and resolved conversations; force pushes and deletion are blocked.
• The production environment is restricted to protected main, with production values entered through the secure user-controlled flow.
• A separately authorized merge is verified on remote main.
• The guarded first deployment succeeds, or a failed deployment rolls back successfully and this issue remains open.
• The temporary environment reviewer gate is removed only after first-run evidence, leaving future validated main merges automatic.
• Final evidence records the pull request, merge commit, deployment, checks, release status, limitations, and next action.
• Issue closure and branch cleanup are separately authorized.

Validation plan

• Run the repository tool-discovery script.
• Run the reusable PowerShell public-site validator.
• Lint the PHP layout and development router.
• Run shell syntax validation and the deployment script's temporary-directory self-test.
• Run git diff --check and targeted searches for old versions, explicit internal index.html links, inconsistent canonical domains, private paths, secrets, and nested public roots.
• Preview representative desktop/mobile routes and a nested missing route with the approved PHP development router.
• Require GitHub Actions validation before merge.
• For the guarded first deployment, verify target identity, backup, every sitemap route, deployed version, true 404, canonical redirects, deployment metadata, health, and rollback behavior.

Known limitations and dependencies

• The repository policy-sync check cannot run because scripts/Sync-CodexAgents.ps1 is absent; no replacement will be invented or installed in this scope.
• Production setup requires a user-controlled Cloudron dashboard/API hostname and dedicated app-operator token; neither belongs in issue text or chat.
• Exact Apache and reverse-proxy behavior requires guarded production evidence (or a separately available safe Apache preview).
• The initial workflow merge will be held behind a temporary production-environment reviewer gate.

[bmurphy-apescic]

Planning and isolation milestone:

• Approved scope is recorded in the issue body.
• Verified remote default branch: main at a1d494caf3cc372c86e286f1af8458fa1e6ecce0.
• Created local issue branch codex/feature/5-cloudron-main-deploy from origin/main.
• Working tree was clean before branch creation.
• Implementation is starting on the issue branch; no commit, push, pull request, merge, deployment, or production change is authorized or performed at this milestone.
• Policy-sync validation remains blocked because the repository-required scripts/Sync-CodexAgents.ps1 helper is absent.

[bmurphy-apescic]

Paused safely at the user's request.

Completed before pause:

• GitHub About description, homepage URL, and approved topics were set and re-read.
• Repository automatic branch deletion was disabled so the issue branch can remain through merge/deployment verification.
• The guarded production environment was created with bmurphy-apescic as the temporary required reviewer, self-review permitted, and deployment limited to protected branches.
• Local issue branch codex/feature/5-cloudron-main-deploy remains based on verified origin/main.

Safe resume state:

• Working tree is clean; no repository file edits are present.
• No files are staged.
• No commit, push, pull request, merge, deployment, production file change, ruleset, or issue closure has occurred.
• No Cloudron secrets have been configured or requested.
• Implementation, validation, route preview, production-secret setup, required-check appearance, and the main ruleset remain pending.

[bmurphy-apescic]

Implementation resumed on 2026-08-13 after re-verifying the paused state.

• Issue branch codex/feature/5-cloudron-main-deploy remains clean and exactly based on current origin/main at a1d494caf3cc372c86e286f1af8458fa1e6ecce0.
• GitHub About metadata, automatic-branch-deletion setting, and the guarded production environment remain configured as recorded.
• Repository implementation is now in progress in the approved public-site, documentation/safety, and validation/deployment-script scopes.
• No commit, push, pull request, merge, deployment, production access, or Cloudron secret configuration is being performed in this phase.
• The policy-sync check remains blocked because scripts/Sync-CodexAgents.ps1 is absent.

[bmurphy-apescic]

Paused safely again at the user's request on 2026-08-13.

Completed and retained as unstaged working-tree edits:

• Root README rewrite and repository safety/release files (.gitignore, .gitattributes, root VERSION, root CHANGELOG.md).
• Focused public-site v3.2.1b hygiene edits, including routing/error handling, clean internal links, metadata, synchronized public version/changelog/Change Log Hub/footer/template records, and sitemap dates.

Safe resume state:

• Current branch remains codex/feature/5-cloudron-main-deploy.
• No files are staged and no commit, push, pull request, merge, deployment, production access, ruleset, or issue closure occurred.
• No conflict markers were found.
• Validation/preview/deployment scripts and .github/workflows/website.yml are not yet present because that workstream was interrupted at the pause.
• Full diff review, validators, deployment self-test, browser preview, and secret/scope audit remain pending; no implementation validation pass is claimed yet.
• README link review found https://account.myapes.me.uk/ currently fails DNS resolution; this existing public/private account boundary is retained and must be reported as an external blocker unless it recovers.
• Policy synchronization remains blocked because scripts/Sync-CodexAgents.ps1 is absent.