orchestration beginning

docs/BUILD_DEPLOY.md

@@ -0,0 +1,62 @@
+# Android Cast build ecosystem
+
+## Shared authentication
+
+All web consoles (Crashes, Tickets, Builder) share:
+
+| Setting | Value |
+|---------|--------|
+| Session name | `ac_crash_sess` |
+| Cookie path | `/app/androidcast_project` |
+| User store | MariaDB `users` table (same DB as crashes) |
+| PHP auth | `examples/crash_reporter/backend/src/Auth.php` |
+
+Sign in once on any console; the session cookie is valid for `/crashes/`, `/build/`, and future apps under the same path prefix.
+
+Orchestration generates matching configs:
+
+- `orchestration/runtime/crash-config.php`
+- `orchestration/runtime/build-config.php`
+
+Both use `${MARIADB_USER}` / `${MARIADB_PASSWORD}` from `orchestration/.env`.
+
+## Local stack
+
+```bash
+cd orchestration
+./deploy.sh
+```
+
+| URL | Purpose |
+|-----|---------|
+| `http://localhost:8080/app/androidcast_project/` | Hub landing |
+| `…/crashes/` | Crash / ticket console |
+| `…/build/` | APK builder console |
+| `…/v0/ota/` | Published OTA artifacts (when auto-deploy enabled) |
+
+Direct debug ports: crashes `:8082`, builder `:8083`.
+
+## Trigger a build
+
+1. Open Builder → sign in (default dev user from crash schema seed).
+2. Set git ref, pipeline options, OTA channel.
+3. **Start build** → detail page polls log every 1s.
+4. Artifacts land in `out/builds/<id>/`; optional OTA copy to `orchestration/runtime/ota-artifacts/`.
+
+## Docker CI
+
+- Image version label: `00.BB.CC.DDDD` (see root `Dockerfile`).
+- Host wrapper: `scripts/docker-build-runner.sh`
+- In-container pipeline: `scripts/ci-build-and-publish-ota.sh`
+- OTA generator: `scripts/generate-ota-v0.sh [channel]`
+
+## CircleCI
+
+- Pipeline description: `build.config.yml`
+- Local CLI stub: `.circleci/config.yml` (`circleci config validate`)
+
+## Production notes
+
+- Mount builder PHP with Docker socket (build host only).
+- FE nginx: read-only OTA under `/v0/ota/`; BE RWX on artifact mount.
+- Keep `session_cookie_path` identical across all PHP apps behind the hub.