toga-ai 1.0.208 → 1.0.209

package/knowledge/1.0/apps/tools/INDEX.md

@@ -6,3 +6,4 @@
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php |
+| [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json |

package/knowledge/1.0/apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md

@@ -0,0 +1,126 @@
+---
+title: Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: workflow
+status: active
+updated: 2026-06-26
+owners: [jcardinal]
+files:
+  - tools/.ebextensions/004_http_to_https.config
+  - tools/.ebextensions/006_mount-s3fs.config
+  - tools/.ebextensions/007_setup_export_cache_folders.config
+  - tools/.ebextensions/008_setup_ldap.config
+  - tools/.ebextensions/009_setup_phpini.config
+  - tools/.ebextensions/020_setup_git_libraries.config
+  - tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config
+  - tools/ebs/git.json
+related:
+  - ../architecture.md
+---
+
+## Summary
+
+How the **Tools** 1.0 app boots on Elastic Beanstalk running
+`PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. The EB platform was upgraded from
+Amazon Linux 2 (AL2) to Amazon Linux 2023 (AL2023), which changes package names, the proxy
+(nginx instead of Apache), the PHP ini scan directory, and how credentials reach the
+instance. The `.ebextensions/*.config` files run alphabetically and are merged by EB; getting
+them wrong leaves the app booting without `/var/www/library` and serving 500s on every
+request. This doc is the migration checklist and the durable AL2023 gotchas learned doing it.
+
+## AL2023 package migration checklist
+
+When migrating any 1.0 app's `.ebextensions` from AL2 to AL2023, rename/remove these yum
+packages (AL2023 uses different names for the same libraries):
+
+- `libstdc++48` → `libstdc++`
+- `php73-ldap` → `php-ldap` (in `008_setup_ldap.config`)
+- **Remove `libcurl: []` entirely** — AL2023 ships `libcurl-minimal` pre-installed, and adding
+  `libcurl` to the yum packages list causes a package-conflict error that fails the deploy.
+
+## How it works
+
+### PHP ini — write the file directly, do not run a script
+
+`009_setup_phpini.config` writes `/etc/php.d/application.ini` with a cfn-init **`files:`**
+block, **not** a container_command that runs a PHP script. On AL2023, `/etc/php.d/` is the
+PHP ini scan directory, and cfn-init `files:` runs before container_commands and before
+PHP-FPM starts, so the file is guaranteed present at startup with no PHP execution needed.
+
+The old approach ran `ebs/setup_phpini.php` (now superseded) which called
+`php_ini_scanned_files()`, parsed it to find the scan dir, and wrote there. On AL2023 that
+failed silently (it was wrapped in `ignoreErrors: true`), so `include_path` never picked up
+`/var/www/library`, producing fatal `require_once('_.php')` errors at runtime.
+
+The `application.ini` sets `include_path = ".:/var/www/library"`, upload/post limits (16M),
+`memory_limit = 2G`, `display_errors`, the `redis.so` extension, and the rediscluster session
+handler (`session.save_path` points at the ElastiCache cluster cfg endpoint). Session GC
+maxlifetime is 4 days.
+
+### Cloning the libraries — bash, not the CodePipeline PHP script
+
+`020_setup_git_libraries.config` clones the framework libraries onto the instance. The old
+`setup_git_libraries.php` (downloaded from S3) requires a DB connection to the `Logs` database
+and a matching row in the `CodePipelineEnvironments` table; for a new app with **no**
+CodePipeline it exits silently without cloning anything, so the app boots without
+`/var/www/library` and 500s on every request.
+
+The replacement is pure bash via a cfn-init `files:` block that writes
+`/tmp/clone_git_repos.sh` (mode `000755`) plus a `container_commands` entry that runs
+`bash /tmp/clone_git_repos.sh`. It clones:
+
+- `agilantsolutions/library`   branch `_production` → `/var/www/library`
+- `agilantsolutions/resources` branch `_production` → `/var/app/ondeck/resources`
+
+`ebs/git.json` was corrected to match: branch `_production` for both repos and the resources
+path set to `/var/app/ondeck/resources`.
+
+### Duplicate config neutralization
+
+EB merges every `.config` alphabetically; two configs with **identical** `container_commands`
+keys silently overwrite each other, causing unpredictable failures (the redis build ran twice;
+an http→https collision obscured failure diagnosis). Two duplicate pairs were neutralized
+(replaced with a comment), keeping the canonical one of each:
+
+- `004_enforce_http_to_https.config` (dup of `004_http_to_https.config`) — neutralized
+- `010_setup_redis_sessions.config` (dup of `010_setup_redis.config`) — neutralized
+
+### ignoreErrors on non-fatal infrastructure commands
+
+Several `container_commands` write to system paths that do not exist on AL2023 (e.g.
+`/etc/httpd/conf.d/` — AL2023 EB uses **nginx**, not Apache, as the reverse proxy). These were
+marked `ignoreErrors: true` in `004`, `006`, `007`, `009`, and `050` so a non-fatal failure
+does not block the deploy. This also covers `006`'s `01_credentials` step: modern EB uses IAM
+roles, so `AWS_SECRET_KEY` / `AWS_ACCESS_KEY_ID` are not injected into `$_SERVER` and the
+s3fs credential write fails cleanly. Use `ignoreErrors` only on genuinely non-fatal infra
+setup — the git clone (`020`) deliberately does **not** use it (see gotchas).
+
+## Gotchas (durable AL2023 / EB rules)
+
+- **Write new-deploy files to `/var/app/ondeck/<path>`, never `/var/www/html/<path>` during
+  `container_commands`.** While container_commands run, `/var/www/html` still symlinks to the
+  **old** app. After the deploy swap, `/var/app/ondeck` becomes `/var/app/current`
+  (= `/var/www/html`). Writing to `/var/www/html` during container_commands writes into the
+  currently-running old app.
+- **Only `/var/log/eb-activity.log` (and `cfn-init.log`) are captured in EB bundle snapshots.**
+  Custom log files under `/var/log/` are invisible unless you SSH the instance. Deploy scripts
+  should log to `/var/log/eb-activity.log`.
+- **CodePipeline-dependent scripts are no-ops for apps without a pipeline.**
+  `setup_git_libraries.php` silently does nothing when the DB has no `CodePipelineEnvironments`
+  row — fatal for a brand-new app, since nothing gets cloned and the failure is silent.
+- **Make clone failures block the deploy.** The bash clone script does `exit 1` on clone
+  failure so the deploy fails visibly, rather than succeeding and serving 500s.
+- **PATH is unreliable in the cfn-init execution environment** — resolve binaries defensively,
+  e.g. `GIT=$(which git || echo /usr/bin/git)`.
+- **cfn-init `files:` runs before `container_commands`** — the correct pattern for writing a
+  script and then executing it in the same config.
+
+## Change history
+- 2026-06-26 — Documented the AL2 → AL2023 (PHP 8.5) EB migration for Tools: package renames
+  (`libstdc++48`→`libstdc++`, `php73-ldap`→`php-ldap`, drop `libcurl`), php ini via cfn-init
+  `files:` writing `/etc/php.d/application.ini`, bash-based library clone replacing the
+  CodePipeline PHP script, duplicate-config neutralization, `ignoreErrors` on non-fatal infra
+  commands, and the ondeck-path / eb-activity.log / pipeline-noop gotchas (jcardinal)

package/knowledge/INDEX.md

@@ -12,7 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 4 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 5 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.208",
+  "version": "1.0.209",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",