270 lines
14 KiB
Markdown
270 lines
14 KiB
Markdown
# Phase 12: Metatron Student ERP — Deployment and Mobile App Release Preparation Report
|
|
|
|
**Date:** October 15, 2026
|
|
**Auditor/Release Engineer:** Antigravity Autonomous Agent
|
|
**Environment:** Backend: Odoo 19 Community Edition (`metatron_academic`) | Database: PostgreSQL 15 (`metatron_aca_erp`) | Mobile App: Flutter (`flutter_app/`)
|
|
**Current Branch:** `main`
|
|
|
|
---
|
|
|
|
## 1. Baseline Branch, Commit, Working-Tree Status, and Unpushed Commits
|
|
|
|
- **Active Branch:** `main`
|
|
- **Release Preparation HEAD Commit:** `921ddc9`
|
|
- Message: `chore(release): configure deployment architecture, environment security, and release signing`
|
|
- **Preceding Audit Baseline Commit:** `e5d3fdc` (`fix(education): harden production readiness and access controls`)
|
|
- **Remote Tracking:** `origin/main` (at `a20b916` / `mobile_api`)
|
|
- **Unpushed Commits:** **9 commits ahead of `origin/main`** (no automatic push performed):
|
|
1. `921ddc9` — `chore(release): configure deployment architecture, environment security, and release signing`
|
|
2. `e5d3fdc` — `fix(education): harden production readiness and access controls`
|
|
3. `1277f7a` — `feat(education_student): add secure profile and document management`
|
|
4. `ff2d790` — `feat(education_finance): integrate student fees and payment tracking`
|
|
5. `bce010f` — `feat(education_announcements): integrate student notices and notifications`
|
|
6. `1d40349` — `feat(education_timetable): complete schedule management and mobile integration`
|
|
7. `232e22e` — `feat(education_attendance): complete attendance workflow and mobile integration`
|
|
8. `2b4b4ae` — `feat(education_exam): implement marks entry, grading, and secure result publication`
|
|
9. `69d69f0` — `feat(flutter_app): initialize Phase 4 Flutter mobile application with Riverpod, Dio, GoRouter, Material 3, and live Odoo session auth`
|
|
- **Working Tree Status:** Clean (all release preparation configs and manifests tracked/committed; report file generated).
|
|
|
|
---
|
|
|
|
## 2. Security and Configuration Findings
|
|
|
|
1. **Root Repository Hygiene:**
|
|
- **Finding:** The root `.gitignore` only ignored `.pyc` and `.DS_Store`. Local database dumps, private keys, `.env` files, and keystores were vulnerable to accidental tracking.
|
|
- **Remediation:** Hardened `.gitignore` to strictly ignore `.env*`, `*.dump`, `*.sql`, `*.tar.gz`, `*.key`, `*.pem`, `*.p12`, `*.jks`, `*.keystore`, `key.properties`, and build artifacts.
|
|
2. **API Endpoint & Host Hardcoding:**
|
|
- **Finding:** `ApiConfig` previously fell back to `http://localhost:10008` even in release builds if `--dart-define=API_BASE_URL` was omitted.
|
|
- **Remediation:** Implemented `AppEnvironment` (`development`, `staging`, `production`). In production mode, fallback to localhost is prohibited; requests fail cleanly with a structured `NOT_CONFIGURED` exception prompting the operator or user to set the API endpoint in Settings.
|
|
3. **HTTPS Enforcement:**
|
|
- **Finding:** Release builds could theoretically connect over unencrypted cleartext HTTP if an insecure URL was supplied.
|
|
- **Remediation:** Added Android Network Security Configuration (`res/xml/network_security_config.xml`) that disallows cleartext HTTP traffic across all domains by default, permitting HTTP only for local loopbacks (`localhost`, `10.0.2.2`) during debug/development.
|
|
4. **Credential Scanning:**
|
|
- **Finding:** Verified all tracked source code in `addons/` and `flutter_app/`. No actual production private keys, production passwords, or third-party secret tokens are committed. Only field schemas and mock fallbacks for unit tests exist.
|
|
5. **Debug Output Sanitization:**
|
|
- **Finding:** `developer.log` and request interceptors in `ApiClient` are strictly gated with `if (kDebugMode)`, ensuring no sensitive student profiles, session tokens, or transaction payloads are emitted into device system logs in release builds.
|
|
|
|
---
|
|
|
|
## 3. Backend Deployment Requirements
|
|
|
|
### Architecture Overview
|
|
The production deployment decouples services into three tiers:
|
|
1. **Edge Reverse Proxy (Nginx/Traefik):** Handles TLS 1.3 / HTTPS termination, rate limiting, request buffering, and static caching.
|
|
2. **Application Tier (Odoo 19 Community):** Runs in multiprocessing worker mode (`workers = 5`), with separated longpolling port 8072 for websocket events.
|
|
3. **Database Tier (PostgreSQL 15):** Placed on an internal Docker bridge network with no external port exposure.
|
|
|
|
### Key Deployment Files Created
|
|
- **`deploy/docker-compose.prod.yml`**: Production compose configuration with container health checks, log rotation (`json-file`, max 50MB x 5), internal network isolation, and environment-driven credentials.
|
|
- **`deploy/odoo.prod.conf`**: Hardened Odoo configuration with `list_db = False` (disabling database manager), `proxy_mode = True`, memory soft/hard limits, and CPU limits.
|
|
- **`deploy/nginx/metatron_erp.conf`**: Production Nginx configuration with HTTP-to-HTTPS 301 redirection, HSTS, security headers, 25MB body limit for student uploads, and WebSocket proxying.
|
|
- **`deploy/.env.example`**: Environment variable template for database credentials, domain names, and worker counts.
|
|
|
|
---
|
|
|
|
## 4. Backup and Recovery Instructions
|
|
|
|
A standalone automated utility is established at `deploy/backup_restore.sh`.
|
|
|
|
### Manual Backup Commands
|
|
```bash
|
|
# 1. Database backup (compressed custom format)
|
|
docker exec -t metatron_academic_db pg_dump -U odoo -Fc metatron_aca_erp > metatron_aca_erp_$(date +%Y%m%d_%H%M%S).dump
|
|
|
|
# 2. Filestore archive (attachments, student photos, certificate PDFs)
|
|
docker exec metatron_academic tar -czf - -C /var/lib/odoo/filestore metatron_aca_erp > filestore_metatron_aca_erp_$(date +%Y%m%d_%H%M%S).tar.gz
|
|
```
|
|
|
|
### Automated Utility Usage
|
|
```bash
|
|
# Full backup (creates dump, tar.gz archive, and SHA256 checksums):
|
|
./deploy/backup_restore.sh backup /path/to/backup_destination
|
|
|
|
# Verification of backup archives:
|
|
./deploy/backup_restore.sh verify /path/to/backup.dump /path/to/filestore.tar.gz
|
|
|
|
# Controlled restore to an isolated staging database:
|
|
./deploy/backup_restore.sh restore /path/to/backup.dump /path/to/filestore.tar.gz metatron_aca_erp_staging
|
|
```
|
|
|
|
*Verification test: Verified against live container `metatron_academic_db` and `metatron_academic`. Successfully generated valid 7.26 MB database dump and 15.18 MB filestore archive.*
|
|
|
|
---
|
|
|
|
## 5. Development, Staging, and Production API Configuration
|
|
|
|
The mobile app supports dynamic compile-time environment flags via `--dart-define`:
|
|
|
|
| Environment | Build Flag | Target URL Example | Cleartext Permitted |
|
|
|---|---|---|---|
|
|
| **Development** | Default (no flag) | `http://10.0.2.2:10008` (Android) / `http://localhost:10008` | Yes (Emulator loopback) |
|
|
| **Staging** | `--dart-define=ENVIRONMENT=staging --dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu` | `https://staging-erp.yourdomain.edu` | No |
|
|
| **Production** | `--dart-define=ENVIRONMENT=production --dart-define=API_BASE_URL=https://erp.yourdomain.edu` | `https://erp.yourdomain.edu` | No (HTTPS enforced) |
|
|
|
|
### Runtime Fallback & Settings Screen
|
|
If built without compile-time URL definitions or when connecting to a local campus network server, students or testing personnel can navigate to **Settings Screen -> API Server Address** and configure the custom base URL directly in the app.
|
|
|
|
---
|
|
|
|
## 6. Android Build and Signing Instructions
|
|
|
|
### Package & Configuration Summary
|
|
- **Package Name / Application ID:** `in.metatroncube.metatron_student_erp`
|
|
- **Application Label:** `Metatron Student ERP`
|
|
- **Min SDK:** 21 (Android 5.0 Lollipop)
|
|
- **Target SDK:** 34 (Android 14)
|
|
- **Version:** `1.0.0+1` (defined in `pubspec.yaml`)
|
|
- **Permissions Declared:**
|
|
- `android.permission.INTERNET`
|
|
- `android.permission.ACCESS_NETWORK_STATE`
|
|
- **Network Security Config:** `flutter_app/android/app/src/main/res/xml/network_security_config.xml`
|
|
|
|
### Production Keystore Configuration
|
|
1. Generate release keystore (keep outside git repository):
|
|
```bash
|
|
keytool -genkey -v -keystore ~/metatron-release-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias metatron_release
|
|
```
|
|
2. Create `flutter_app/android/key.properties` from template:
|
|
```bash
|
|
cp flutter_app/android/key.properties.example flutter_app/android/key.properties
|
|
```
|
|
3. Populate with your private credentials:
|
|
```properties
|
|
storePassword=your_keystore_password
|
|
keyPassword=your_key_password
|
|
keyAlias=metatron_release
|
|
storeFile=/absolute/path/to/metatron-release-keystore.jks
|
|
```
|
|
*(Note: `build.gradle.kts` automatically loads `key.properties` when present, and safely defaults to debug signing for internal QA if absent).*
|
|
|
|
### Release Build Commands
|
|
```bash
|
|
cd flutter_app
|
|
|
|
# 1. Google Play Store Release (Android App Bundle - AAB):
|
|
flutter build appbundle --release \
|
|
--dart-define=ENVIRONMENT=production \
|
|
--dart-define=API_BASE_URL=https://erp.yourdomain.edu
|
|
|
|
# 2. Direct Distribution / Internal Staging QA (Split Per-ABI APKs):
|
|
flutter build apk --release --split-per-abi \
|
|
--dart-define=ENVIRONMENT=staging \
|
|
--dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu
|
|
```
|
|
|
|
---
|
|
|
|
## 7. iOS Build and Signing Instructions
|
|
|
|
### Package & Configuration Summary
|
|
- **Bundle Identifier:** `in.metatroncube.metatronStudentErp`
|
|
- **Display Name:** `Metatron Student ERP`
|
|
- **Deployment Target:** iOS 12.0+
|
|
- **Privacy Usage Descriptions:**
|
|
- `NSPhotoLibraryUsageDescription`: Required for uploading student profile photos and verification certificates.
|
|
- `NSCameraUsageDescription`: Required for capturing physical identity documents and verification photos.
|
|
- **App Transport Security (ATS):** Strict HTTPS enforcement by default.
|
|
|
|
### Archiving and App Store Connect Submission Steps
|
|
1. Open the iOS workspace in Xcode:
|
|
```bash
|
|
open flutter_app/ios/Runner.xcworkspace
|
|
```
|
|
2. In **Signing & Capabilities**, select your Apple Developer Team and Provisioning Profile.
|
|
3. Build the release archive from CLI or Xcode:
|
|
```bash
|
|
cd flutter_app
|
|
flutter build ipa --release \
|
|
--dart-define=ENVIRONMENT=production \
|
|
--dart-define=API_BASE_URL=https://erp.yourdomain.edu
|
|
```
|
|
4. Upload to App Store Connect / TestFlight:
|
|
```bash
|
|
xcrun altool --upload-app --type ios -f build/ios/ipa/*.ipa --apiKey <API_KEY> --apiIssuer <ISSUER_ID>
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Test and Build Results
|
|
|
|
### Automated Test Matrix
|
|
| Test Suite | Command | Result | Notes |
|
|
|---|---|---|---|
|
|
| **Flutter Static Analysis** | `flutter analyze` | **PASSED** (0 issues) | Strict type checking & zero lints |
|
|
| **Flutter Unit & Widget Tests** | `flutter test` | **PASSED** (64 / 64 passed) | Full coverage of UI widgets, providers, and state models |
|
|
| **Flutter Live Integration** | `flutter test test/live_odoo_integration_test.dart` | **PASSED** (12 / 12 passed) | End-to-end auth, profile, timetable, exams, fees, documents, certificates |
|
|
| **Odoo Backend Automated Tests** | `odoo --test-tags /education_*` | **PASSED** (70 / 70 passed) | 0 failed, 0 errors across all 8 modules |
|
|
| **Flutter Web Release Build** | `flutter build web --release` | **PASSED** (`✓ Built build/web`) | Verified tree-shaking and production compilation |
|
|
| **Android Release Build** | `flutter build apk --release` | **ENVIRONMENT-BLOCKED** | Host machine lacks local Android SDK toolchain |
|
|
| **Android App Bundle** | `flutter build appbundle --release`| **ENVIRONMENT-BLOCKED** | Host machine lacks local Android SDK toolchain |
|
|
| **iOS Release Archive** | `flutter build ipa --release` | **ENVIRONMENT-BLOCKED** | Host machine lacks full Xcode developer installation & CocoaPods |
|
|
|
|
---
|
|
|
|
## 9. Required Privacy Policies and Store Submission Prerequisites
|
|
|
|
### Play Store & App Store Compliance Checklist
|
|
1. **Privacy Policy URL:**
|
|
- Must be hosted publicly (e.g. `https://yourdomain.edu/privacy-policy`).
|
|
- Must state that student personal data (name, email, phone, enrollment ID) is collected exclusively for educational record administration and is not shared with third-party advertisers.
|
|
2. **Account Deletion / Request Policy:**
|
|
- App Store and Play Store require providing students an option or URL to request account closure or data rectification through the institution's registrar office.
|
|
3. **Data Safety Form (Google Play Console):**
|
|
- Personal info: Name, email, student ID collected for app functionality.
|
|
- Financial info: Fee payment records (no credit card details stored on-device).
|
|
- Photos and documents: Uploaded exclusively for institutional identity verification.
|
|
- Encryption in transit: Yes (HTTPS/TLS 1.3).
|
|
4. **App Store Review Demo Credentials:**
|
|
- Provide active demo credentials (`demo.student`) in the App Store Review Information notes.
|
|
|
|
---
|
|
|
|
## 10. Outstanding Blockers and Recommended Next Actions
|
|
|
|
### Blockers Before Public Release
|
|
1. **Production Domain & SSL Certificates:**
|
|
- Real institutional domain (e.g. `erp.yourdomain.edu`) and valid Let's Encrypt / commercial SSL certificate are required.
|
|
2. **CI/CD Signing Environment:**
|
|
- Android release keystore (`key.properties`) must be provisioned in the CI/CD secret manager (GitHub Actions / GitLab CI).
|
|
- Apple Developer Team membership and distribution certificate must be linked in Xcode.
|
|
3. **Odoo Database Master Password:**
|
|
- Replace placeholder master password in `deploy/odoo.prod.conf` with a securely vaulted secret.
|
|
|
|
---
|
|
|
|
## 11. Exact Commands for Eventual Deployment and Release
|
|
|
|
### Staging Deployment (Backend)
|
|
```bash
|
|
# 1. Clone repository to staging server
|
|
git clone <REPO_URL> metatron_erp && cd metatron_erp
|
|
|
|
# 2. Configure environment
|
|
cp deploy/.env.example deploy/.env
|
|
# Edit deploy/.env with staging database password and domain
|
|
|
|
# 3. Launch staging containers
|
|
docker compose -f deploy/docker-compose.prod.yml --env-file deploy/.env up -d
|
|
|
|
# 4. Restore sanitized database backup
|
|
./deploy/backup_restore.sh restore /path/to/staging_backup.dump /path/to/filestore.tar.gz metatron_aca_erp
|
|
```
|
|
|
|
### Production Release (Mobile)
|
|
```bash
|
|
cd flutter_app
|
|
|
|
# Android App Bundle for Google Play
|
|
flutter build appbundle --release \
|
|
--dart-define=ENVIRONMENT=production \
|
|
--dart-define=API_BASE_URL=https://erp.yourdomain.edu
|
|
|
|
# iOS IPA for App Store / TestFlight
|
|
flutter build ipa --release \
|
|
--dart-define=ENVIRONMENT=production \
|
|
--dart-define=API_BASE_URL=https://erp.yourdomain.edu
|
|
```
|
|
|
|
---
|
|
*Phase 12 Deployment and Mobile App Release Preparation complete. Awaiting user review and authorization.*
|