next/side sync

2026-07-29 04:38:53 +03:00 · 2026-05-26 13:14:14 +02:00
parent ac8d4ea341
commit ef36f91b82
35 changed files with 1828 additions and 16 deletions
--- a/docs/CRASH_REPORTER.md
+++ b/docs/CRASH_REPORTER.md
@@ -22,7 +22,8 @@ Deploy tuning via app-private `files/settings.json` (see `examples/settings.json

 ## Backend

-PHP console and ingest API: `examples/crash_reporter/backend/` — see [README](../examples/crash_reporter/backend/README.md).
+PHP console and ingest API: `examples/crash_reporter/backend/` — see [README](../examples/crash_reporter/backend/README.md).  
+Production nginx/hosts: [INFRA.md](INFRA.md).

 Roadmap: `examples/crash_reporter/ROADMAP.md`.

--- a/docs/INFRA.md
+++ b/docs/INFRA.md
@@ -0,0 +1,202 @@
+# Android Cast — production infrastructure
+
+**Read this first** after a context reset, before changing nginx, deploy paths, or URLs.
+
+| Doc | When |
+|-----|------|
+| **This file** | Topology, hosts, ports, sshfs, agent rules |
+| [examples/app_hub/DEPLOY.md](../examples/app_hub/DEPLOY.md) | Hub landing only (BE `listen 80`) |
+| [examples/crash_reporter/backend/README.md](../examples/crash_reporter/backend/README.md) | PHP, MariaDB, tickets, ingest |
+| [docs/GIT_FLOW.md](GIT_FLOW.md) | Branches, `next`, no direct commits to `master` |
+| [docs/TICKETS_ROADMAP.md](TICKETS_ROADMAP.md) | Tickets, Gitea, alpha delegation |
+
+---
+
+## 1. Topology
+
+```text
+Internet / LAN
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  FE — Gentoo HVM                    │
+│  Public: https://apps.f0xx.org      │
+│  TLS termination, nginx reverse proxy│
+└──────────────┬──────────────────────┘
+               │  proxy_pass http://artc0.intra.raptor.org:80
+               │  (default location /)
+               ▼
+┌─────────────────────────────────────┐
+│  BE — Alpine VM 10.7.16.128         │
+│  nginx: /etc/nginx/conf.d/apps.conf│
+│  PHP-FPM unix socket                │
+│  MariaDB: androidcast_crashes       │
+└─────────────────────────────────────┘
+```
+
+| Role | Host | Notes |
+|------|------|--------|
+| **FE** | Gentoo, `apps.f0xx.org` | Almost all app traffic → BE **:80** |
+| **BE** | Alpine `artc0.intra.raptor.org` | App vhost lives in **`listen 80`** for FE traffic |
+| **Jump SSH** | `f0xx.org:222` → Alpine `:22` | `~/.ssh/config` host **`alpine-be`** |
+| **Git origin** | `git://f0xx.org/android_cast` | Integration branch **`next`** |
+
+---
+
+## 2. Port 8089 — not the androidcast vhost
+
+**Do not** configure or document the project hub or crash console on **`:8089`** for this installation.
+
+| Port | Service |
+|------|---------|
+| **80** | **Canonical** androidcast vhost on BE (hub + crashes when FE uses `location /` or explicit `:80` upstream) |
+| **443** | BE TLS (used by some FE `proxy_pass` rules, e.g. `apps.f0xx.org` → `https://artc0:443/.../crashes/`) |
+| **8089** | **Other** stack (e.g. **Janus** `/janus/`) — **not** androidcast nginx vhost |
+
+Wrong FE pattern (remove if present on **`artc0.f0xx.org`**):
+
+```nginx
+proxy_pass https://artc0.intra.raptor.org:8089/app/androidcast_project/;  # BAD for hub
+```
+
+Correct public path for hub:
+
+`https://apps.f0xx.org/app/androidcast_project/` → FE `location /` → `http://artc0.intra.raptor.org:80` → BE `listen 80` locations.
+
+---
+
+## 3. Public URLs
+
+| URL | Component |
+|-----|-----------|
+| `https://apps.f0xx.org/app/androidcast_project/` | Static hub (`examples/app_hub/index.html`) |
+| `https://apps.f0xx.org/app/androidcast_project/crashes/` | PHP crash + tickets console |
+| `https://apps.f0xx.org/app/androidcast_project/crashes/api/upload.php` | Device crash upload (no session) |
+
+Legacy hostname **`f0xx.org`** may still appear in app `settings.json` examples; production ingest/scripts prefer **`apps.f0xx.org`**.
+
+---
+
+## 4. Disk layout (BE)
+
+Web root prefix:
+
+`/var/www/localhost/htdocs/apps/app/androidcast_project/`
+
+| Path on BE | Repo |
+|------------|------|
+| `.../androidcast_project/android_cast/` | Full git tree (crash backend, app sources) |
+| `.../androidcast_project/index.html` | `examples/app_hub/index.html` (copy or symlink) |
+| `.../android_cast/examples/crash_reporter/backend/public/` | PHP document root for crashes |
+
+`config.php` **`base_path`** must be exactly:
+
+`/app/androidcast_project/crashes`
+
+---
+
+## 5. Nginx — source of truth in repo
+
+| File | Purpose |
+|------|---------|
+| **`examples/crash_reporter/backend/nginx.apps-port80.fragment`** | **Replace** BE `server { listen 80; ... }` — hub + crashes + assets |
+| `examples/crash_reporter/backend/nginx.apps.conf.fragment` | Reference blocks (443-oriented comments) |
+| `examples/crash_reporter/backend/nginx.vm.conf` | Full VM example |
+
+### BE `apps.conf` today (typical)
+
+- **`listen 80`** — often **empty** (only generic `\.php$`) → **public hub 502** until port-80 fragment is applied.
+- **`listen 443 ssl`** — may already contain hub + crashes (direct HTTPS to VM).
+
+FE **`apps.f0xx.org`** uses `proxy_pass http://artc0.intra.raptor.org:80` for `/` — so **hub must be on BE port 80**, not only 443.
+
+### Hub location (correct)
+
+Use **directory** `alias`, not `alias` to a single file:
+
+```nginx
+location /app/androidcast_project/ {
+    alias /var/www/localhost/htdocs/apps/app/androidcast_project/;
+    index index.html;
+}
+```
+
+### Reload (BE only for hub deploy)
+
+```bash
+ssh alpine-be 'sudo nginx -t && sudo rc-service nginx reload'
+```
+
+---
+
+## 6. Local sshfs workspace (not in git)
+
+Edit live configs from the dev machine via mounts under repo **`tmp/`**:
+
+| Mount | Remote |
+|-------|--------|
+| `tmp/FE_gentoo/etc/nginx/` | Gentoo FE nginx |
+| `tmp/BE_alpine/etc/nginx/conf.d/apps.conf` | Alpine BE apps vhost |
+| `tmp/BE_alpine/var/www/localhost/htdocs/apps/...` | BE web tree |
+
+Treat `tmp/` as **local mirrors** — sync/reload on the real host after edits.
+
+---
+
+## 7. FE nginx — two server names
+
+Mounted copy: `tmp/FE_gentoo/etc/nginx/nginx.conf`.
+
+| `server_name` | `location /` | androidcast crashes | Hub `/app/androidcast_project/` |
+|---------------|--------------|---------------------|--------------------------------|
+| **`apps.f0xx.org`** | → `http://artc0:80` | May → `https://artc0:443/.../crashes/` | Via **`location /`** → BE :80 (no extra block needed) |
+| **`artc0.f0xx.org`** | → `http://artc0:80` | Legacy → **:8089** | Legacy → **:8089** — **remove** hub block; prefer apps.f0xx.org |
+
+**Agent default:** fix **BE `listen 80`** first. Change FE only when user asks or to delete wrong **8089** hub overrides on `artc0.f0xx.org`.
+
+---
+
+## 8. Verify
+
+```bash
+# BE directly (simulates FE Host header)
+curl -sS -o /dev/null -w "%{http_code}\n" -H "Host: apps.f0xx.org" \
+  "http://artc0.intra.raptor.org/app/androidcast_project/"
+
+curl -sS -o /dev/null -w "%{http_code}\n" -H "Host: apps.f0xx.org" \
+  "http://artc0.intra.raptor.org/app/androidcast_project/crashes/"
+
+# Public
+curl -sS -o /dev/null -w "%{http_code}\n" \
+  "https://apps.f0xx.org/app/androidcast_project/"
+```
+
+Expect **200** (or **302** → crashes only if you intentionally redirect root).
+
+---
+
+## 9. Backend app (crashes / tickets)
+
+- PHP 8.1+ FPM on Alpine; MariaDB DB **`androidcast_crashes`**.
+- Migration **`003_tickets.sql`** as **MySQL root** if UI says table missing (app user cannot DDL).
+- `Database::requireTicketsTable()` must open PDO before `SHOW TABLES` (fixed in repo).
+- Ingest smoke tickets: `php scripts/ingest_alpha_smoke_tickets.php --url=https://apps.f0xx.org/app/androidcast_project/crashes`
+
+---
+
+## 10. Rules for agents
+
+1. **KISS** — prefer **one** BE change (`listen 80` fragment) over FE + BE + 8089 guesses.
+2. **Never** point androidcast hub/crashes docs at **:8089** for this install.
+3. **Do not** use `alias` to `index.html` as a file path (breaks trailing slash / CSS).
+4. **Do not** commit `tmp/` sshfs trees, `*.log`, or workspace files unless user asks.
+5. **Do not** commit to `master`/`next` directly — use `feature/*` → merge to `next` ([GIT_FLOW](GIT_FLOW.md)).
+6. User may be unwell / slow to deploy — give **short** copy-paste steps, not long runbooks.
+
+---
+
+## 11. Changelog (infra doc)
+
+| Date | Note |
+|------|------|
+| 2026-05-21 | Documented BE-only hub on port 80; 8089 = Janus only; FE `apps` vs `artc0` split |
--- a/docs/TICKETS_ROADMAP.md
+++ b/docs/TICKETS_ROADMAP.md
@@ -0,0 +1,90 @@
+# Tickets, Gitea, and alpha smoke delegation
+
+## Gitea (`/app/androidcast_project/git/`)
+
+Public URL should return Gitea HTML (assets under `/app/androidcast_project/git/assets/…`).
+
+**If clone/push fails while the page loads:**
+
+1. **Clone URL** must include the subpath, e.g.  
+   `https://apps.f0xx.org/app/androidcast_project/git/<owner>/<repo>.git`
+2. **Gitea `app.ini`** on BE (`:3000`):  
+   `ROOT_URL = https://apps.f0xx.org/app/androidcast_project/git/`  
+   `DOMAIN = apps.f0xx.org`
+3. **FE** `nginx.conf` ~983–996: `proxy_pass http://artc0.intra.raptor.org:3000/;` only works if Gitea is configured for that subpath (your HTML manifest suggests it is).
+4. **BE**: Gitea must listen on `10.7.16.128:3000` (or `0.0.0.0:3000`); no extra nginx required unless you proxy git through `:80` too.
+
+Symptom checklist: 502 → Gitea down; broken CSS → `ROOT_URL` wrong; 401 on push → credentials / token; 404 on clone → remote path missing subpath.
+
+---
+
+## Alpha smoke tickets (typical DB id → block)
+
+Ingest order from `tmp/alpha_smoke_round1.txt` (skips pure “pass” rows):
+
+| id (typical) | Block | Theme | Delegation |
+|--------------|-------|--------|------------|
+| 1 | A3 | PIN/cast OK; **rotation + preview NOK** | App: sender preview / rotation crash |
+| 2 | A4 | Video OK; **frame drops, low res, few TX losses** | App: UDP/encoder quality; monitor NDK only if native crashes appear |
+| 3 | A5 | Audio works; **laggy sound** | App: AAC pipeline / jitter buffer |
+| 4 | A6 | Notification resolution | Often lower priority (pass with notes) |
+| 5 | A7 | Stop OK; **wrong lifecycle** (resume, notifications) | App: `CastForegroundService`, notification intents, task stack |
+| 6 | A9 | Repeat soak; **lifecycle** again | Same as #5 |
+| 7 | (manual) | **Delegation / process** | Console: assignees, workflow, comments (this doc) |
+
+Confirm ids in UI (title contains `Alpha smoke A3` etc.).
+
+---
+
+## Console features (implementation)
+
+| Feature | Status |
+|---------|--------|
+| Workflow state (`triage` → `in_progress` → `blocked` / `wont_fix` → `done`) | Migration `004` + UI |
+| Assignees (0..n users, chip picker) | `assignees_json` + API |
+| Comments (thread on ticket) | `ticket_comments` + API |
+| Email notify reporter | Nice-to-have later |
+| **Attachments** (files + links) | Migration `005` + ticket UI |
+| **Google Suite** (OAuth, embed, Chat/Meet hooks) | Phase 2 — see below |
+
+### Attachments (deploy)
+
+```bash
+mysql -u root -p androidcast_crashes < examples/crash_reporter/backend/sql/migrations/005_ticket_attachments.sql
+chown -R www-data:www-data examples/crash_reporter/backend/storage
+```
+
+- **Links:** paste HTTPS URL; Google hosts auto-tagged (Docs, Sheets, Slides, Drive, Meet, Chat, Forms).
+- **Files:** stored under `backend/storage/ticket_attachments/{ticket_id}/`, download via `/api/ticket_attachment.php?id=…`.
+
+### Google Workspace — phase 2 (not implemented)
+
+Requires Google Cloud project, OAuth consent, service account or user OAuth:
+
+| Product | Integration idea |
+|---------|------------------|
+| Docs / Sheets / Slides | Picker API → attach link + optional embed iframe |
+| Drive | File picker + shared-drive ACL |
+| Meet | Attach recording link after call |
+| Chat | Webhook or Chat API for ticket updates |
+| Gmail | Optional notify assignees |
+
+Until then, **paste share links** — the console labels them and opens in a new tab.
+
+**Deploy migration (MariaDB, as root):**
+
+```bash
+mysql -u root -p androidcast_crashes < examples/crash_reporter/backend/sql/migrations/004_ticket_workflow.sql
+```
+
+---
+
+## Agent / engineering queue (from your list)
+
+1. **#1 (A3 NOK)** — Reproduce rotation + preview crash; separate from PIN path.
+2. **#5 / #7 / #6 (lifecycle)** — Audit cold start, recents, notification tap, stop/receive; align with alpha A7/A9.
+3. **#3 (laggy audio)** — Measure end-to-end latency sender → receiver; tune buffer / sync.
+4. **#2 (TX losses)** — Log UDP gaps; recovery already OK — reduce loss if easy win.
+5. **NDK** — Only if crash console shows native reports for these sessions.
+
+Use ticket **comments** for findings; set **workflow** + **assignees** when you hand off.