From 0c6bc1ae16b177e68e2b5b52a9d55f6853393924 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 24 May 2026 12:49:00 +0300 Subject: [PATCH] Document F7_PUSH_SECRET for support webhook and sync f7support secret on regenerate. --- README.md | 110 +++++++++++++++++++++++++++++++++---- scripts/generate-secret.sh | 5 +- 2 files changed, 103 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 97e378f..d944641 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,22 @@ Mobile push delivery for **F7cloud** accounts via Firebase Cloud Messaging. Portable: install on any F7cloud server, configure via `occ`, no hardcoded hostnames. +## Architecture + +```text +F7cloud app (f7support, spreed, …) + │ + ▼ + f7push (this app) ──FCM HTTP v1──► Google FCM ──► Android APK (WebView) + ▲ │ + └──── POST /devices (user session) ──────┘ + APK registers FCM token per account +``` + +- **Server:** f7push stores devices in `oc_f7push_devices`, sends via Firebase service account. +- **Client:** WebView APK (`android-webview`) registers token after login using WebView cookies. +- **FCM:** free transport layer; required for reliable background push on stock Android. + ## Install on a server ```bash @@ -12,15 +28,39 @@ cd /var/www/f7cloud sudo -u www-data php occ app:enable f7push ``` +Database table `oc_f7push_devices` is created by migration on enable/upgrade. + +## Setup checklist (new instance) + +| Step | Action | +|------|--------| +| 1 | Clone repo → `apps/f7push`, `occ app:enable f7push` | +| 2 | Firebase project + Android app `ru.forbion.f7cloud` → `google-services.json` into APK (see android-webview README) | +| 3 | Firebase service account JSON → `occ config:app:set f7push firebase_*` | +| 4 | Build & install APK; user logs in and grants notifications | +| 5 | Test: `POST …/push/test` or send from Firebase Console | + +### forbion.f7cloud.ru (May 2026) + +| Item | Status | +|------|--------| +| f7push v0.1.0 enabled | done | +| `oc_f7push_devices` table | done | +| Firebase project **F7push** (`project_id`: `f7push`) | done | +| APK `google-services.json` + release build v1.5 | done | +| `firebase_project_id` + `firebase_credentials` in occ | done | +| End-to-end push test on device | **pending** | +| `F7_PUSH_SECRET` / webhook for support API | done | + ## Configuration (`occ`) ```bash # Enable / disable sudo -u www-data php occ config:app:set f7push enabled --value=yes -# Firebase (service account JSON from Firebase Console, one line or file) -sudo -u www-data php occ config:app:set f7push firebase_project_id --value=YOUR_PROJECT_ID -sudo -u www-data php occ config:app:set f7push firebase_credentials --value='{"type":"service_account",...}' +# Firebase — from Project settings → Service accounts → Generate new private key +sudo -u www-data php occ config:app:set f7push firebase_project_id --value=f7push +sudo -u www-data php occ config:app:set f7push firebase_credentials --value="$(cat /path/to/service-account.json)" # Optional: default URL when notification has no link sudo -u www-data php occ config:app:set f7push default_click_url --value=https://YOUR-SERVER.f7cloud.ru @@ -31,9 +71,41 @@ sudo -u www-data php occ config:app:set f7push enabled_sources --value='spreed,f # Relay F7cloud bell notifications to push sudo -u www-data php occ config:app:set f7push listen_notifications --value=yes -# API secret (auto-created on first server push if empty, or set manually): +# API secret — shared with support.f7cloud.ru as F7_PUSH_SECRET sudo -u www-data php occ config:app:set f7push api_secret --value='YOUR_SECRET' -# Or: bash scripts/generate-secret.sh --regenerate +# Or regenerate (also updates f7support push_webhook_secret): +bash scripts/generate-secret.sh --regenerate +sudo -u www-data php occ config:app:set f7support push_webhook_secret --value="$(sudo -u www-data php occ config:app:get f7push api_secret)" +``` + +**Secrets:** never commit `firebase_credentials`, `api_secret`, `F7_PUSH_SECRET`, or `google-services.json` to git. + +### support.f7cloud.ru → F7cloud push + +When a support agent replies to a ticket, **support API** calls f7support webhook: + +```env +# support server .env +F7_PUSH_SECRET= +F7_PUSH_URL=https://YOUR-SERVER.f7cloud.ru/ocs/v2.php/apps/f7support/api/v1/push +``` + +```http +POST …/apps/f7support/api/v1/push +X-F7-Push-Secret: +Content-Type: application/json + +{ "userId": "…", "ticketNumber": "…", "ticketSubject": "…", "body": "…" } +``` + +See **f7support** repo: `README.md`, `push.env.example`. + +Verify configuration: + +```bash +sudo -u www-data php occ config:app:get f7push firebase_project_id +curl -H 'OCS-APIRequest: true' -H 'Accept: application/json' \ + 'https://YOUR-SERVER/ocs/v2.php/apps/f7push/api/v1/status' ``` ## API (OCS) @@ -53,8 +125,11 @@ Base: `/ocs/v2.php/apps/f7push/api/v1/` ```json POST /ocs/v2.php/apps/f7push/api/v1/devices +Header: OCS-APIRequest: true +Cookie: + { - "deviceId": "stable-android-id", + "deviceId": "uuid-generated-by-apk", "fcmToken": "...", "platform": "android", "clientApp": "f7cloud-apk" @@ -79,11 +154,26 @@ Header: X-F7-Push-Secret: ## Android APK -Repository: `android-webview` on the same server. +Path on forbion: `/var/www/f7cloud/android-webview/` +Build docs: `README_ANDROID_BUILD.md` in that directory. -1. Add `google-services.json` from Firebase (`applicationId` `ru.forbion.f7cloud`). -2. Build APK; on login the app registers FCM token via `/devices`. +1. Place Firebase `google-services.json` in `android-webview/app/`. +2. `./gradlew assembleRelease` → install APK on device. +3. User logs into F7cloud in WebView; device appears in `GET /devices`. + +APK v1.5 (versionCode 6): `F7PushRegistrar`, `F7FirebaseMessagingService`, channel `f7cloud_default`. + +## Development workflow + +```bash +# Edit in git clone +cd /root/git-sync/f7push +# … changes … +rsync -a --delete /root/git-sync/f7push/ /var/www/f7cloud/apps/f7push/ +sudo -u www-data php occ app:enable f7push # or upgrade if version bumped +git add -A && git commit -m "…" && git push origin master +``` ## Version -0.1.0 — initial release (device registry, FCM send, notification relay, API). +0.1.0 — device registry, FCM send, notification relay, OCS API. diff --git a/scripts/generate-secret.sh b/scripts/generate-secret.sh index 3c3f14e..6b99c2e 100644 --- a/scripts/generate-secret.sh +++ b/scripts/generate-secret.sh @@ -1,12 +1,13 @@ #!/usr/bin/env bash -# Print or set f7push API secret on this F7cloud server. +# Print or set f7push API secret (F7_PUSH_SECRET for support.f7cloud.ru webhook). set -euo pipefail cd /var/www/f7cloud if [[ "${1:-}" == "--regenerate" ]]; then SECRET=$(openssl rand -base64 36 | tr -d '/+=' | head -c 48) sudo -u www-data php occ config:app:set f7push api_secret --value="$SECRET" + sudo -u www-data php occ config:app:set f7support push_webhook_secret --value="$SECRET" echo "$SECRET" else sudo -u www-data php occ config:app:get f7push api_secret 2>/dev/null || true - echo "(If empty, call POST /push once or run with --regenerate)" + echo "(If empty, run with --regenerate)" fi